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C CODE FOR THE PC 

source code, of course 

DBAPrep (embedded SQL to C translator, supports Oracle, Sybase, SQL Server, XDB, Novell XQL, SQLBase, and QE-Lib).$1,500 

Image Compression Library (patented ”VARI” technology, transmit full screen in 15 seconds, includes JPEG, license required).$950 

Virtual Memory Objects (btrees, lists, arrays, and other multiple memory classes in heap, EMM, and swap file; no royalties).$750 

Embedded DOS (full-features, real-time, multitasking, 3.31-compatible DOS for embedded system and self-bootable installations).$375 

NEW! Style (a C++class library to build, maintain and traverse arbitrary, non-taxonomic links between C++objects).$300 

Spell Time (spelling checker for incorporation into text products; no royalty, large dictionary; small and fast).$300 

ZIP Image Processor & Victor Image Library Version 2.0 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 

NEW! The Snooper (Ethernet protocol analyzer for Novell Netware and LAN Manager Networks; capture packets; real-time display).$275 

TUrboTpX (Release 3.0; HP, PS, dot drivers; CM fonts; LaTgX; MetaFont).$250 

Rogue Wave tools.h-(—(- or math.h++ Class Library (extensive docs).each $240 

PxSQL (SQL for Borland's Paradox Engine; ANSI X3.135-1989 SQL-DML standard; network server not required).$180 

Embedded DOS Utility SDK (C source for standard DOS utilities — FDISK, FORMAT COMMAND.COM and eight more).$170 

C-pslib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support).$170 

NEW! VrewPoint (C++graphics library; 32-bit oolor, pattern fill, scroll & bitmap, coordinate tranformatrons).$170 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; specify 5.25” or 3.5” diskettes).each $150 

Delorie GCC for MS-DOS (Version 1.05; includes C++, assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 

Booter Ibolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

NEW! Dr. MD (runtime memory analyzer & debugger; find many memory corruption errors; examine memory usage).$110 

Visions 1.20 (text window user rnterface management system; includes mouse support and background processing).$105 

Updated! SCM (portable Scheme in C, conforms to IEEE and 3.99 specs, garbage collection, mixs with Q SCM3C12/SLIB1B3).$100 

PC/IP (CMU/MIT TCP/IP for PCs; Clarkson drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . $100 

Heapman (application memory management for Windows 3.0; 64K bytes of heap space; includes memory browser/debugger) .$100 

EZBieve (Novell Btrieve access with data dictionary and data manager; no royalties).$100 

EZBase (C interface to dBase files; create, read, wnte & update .DBF and .DBT includes index support).$100 

NEW! Demacs (complete GNU Emacs for DOS; needs djgcc to build; based on 18.55).$100 

NEW! BASH (key-indexed record management system for DOS and Windows DDL; record locking for concurrent access environments).$95 

Script Interpreter (a command script interpreter for DOS-based systems; C-like script language; lots of features).$90 

NEW! HorC++(C++Class Library for Borland’s Paradox Engine).$80 

VMEM (vrrtual memory manager by Blake McBride, Version 3.6, LRU pager, dynamic swap file, image save/restore).$80 

NEW! CPPCOMM (Version 2.0; C++class library for serial communications).$75 

TteeDraw (PostScript display of labeled hierarchical trees; DOS & Windows screen display included; Moen algorithm).$75 

Updated! BGI Printer Driver Tbolkrt (hardcopy drivers for Borland BGI graphics library; Epson, IBM, LaserJet, DeskJet, PaintJet, PostScript) .... $75 
NE W! InfoMagic (X11R5, Thhoe 4.3 BSD, complete GNU, ISODE, KA9Q & NCSA TCP/IP, all TCP/IP docs, DOS tools; 600MB on ISO-9660 CD-ROM)$70 

NE W! Prime Time Freeware (over 1 gigabyte of Unix C code on an ISO-9660 CDROM).$60 

FinanC (large collection of financial function including bond, inventory, stock portfolio, & cash flow).$70 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or C++).each $65 

NEW! ps3d (3-dimensional perspective line drawings with PostScript output).$60 

LDB (Loose Data Binder, persistent data objects for C++; handles pointers between objects) .$60 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

MEM-WING (global memory manager for Windows, supports standard C memory allocation calls to ’’wing” your old C code into Windows) . $55 

Mini IDL (interface generator for complex data; single inheritance, translator & table generator tools, ASCII external form only)).$50 

CALC (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

Floppy TAR (TAR backup and restore on MS-DOS devices; direct access to non-standard devices) .$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

OBJASM (convert .obj files to .asm files; output is MASM compatible) . $50 

Updated! CUPS Version 5.1 (rule-based expert system generator, advanced manuals available at additional cost).$50 

NIH Class Library & Book (basic C++ classes & Data Abstraction and Object-Oriented Programming in C++ in softback by Keith Gorien) $50 

Editor Pack (15 public domain editors; including microEmacs 3.11, Stevie, Elvis, Moke, mg2a, DTE, Jove, & Origami).$50 

MicroC C Compiler (retargets ble C compiler wrth optimizer, libraries, and utilities; lots of docs, very portable, tables for 5 cpu’s).$50 

TOUR (beautiful traveling salesman problem solver, finds minimum length paths quickly, includes graphics & plotting programs) .$40 

NE W! Charting Routines (Version 1.0; produce a number of different kinds of charts from ASCII data files).$40 

DES Encryption* Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; domestic distribution only) . . ! ! $40 

RXC & EGREP Version 2.0 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Database Pack (9 databases -simple to complex; isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

Bison & BYACC(YACC workalike parser generators; documentation; no restrictions on use of BYACC output).$35 

Object-Oriented Programming in C+ + (code from the book by Naba Barkakati).$30 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

REGX Plus (Version 2.0, search and replace string manipulation routines based on regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

UUPC Pack (UUCP for the PQ UUPC Version 1.11 Q by Wonderworks and smail/PC Version 25 by Stephen G Ther).$25 

Updated! PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

"Ifcl Version 6.1 (Ibol Command Language; add shell programming capability to any command line; elegant command line language) .... $25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 236 with docs).$25 

NEW! Hierarchical Data Format (machine-independent data representation; especially good for images; PC port of NCSA code) .$20 

XLISP 2.1 (includes Almy rmprovements).$20 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better, keeps track of software development).$20 

Gperf Version 25 (GNU’s perfect hash table generator; requires DJ gee; includes executable; specify C or C+ +) .each $20 

SDBM (fast, disk-based hash table manager for really large hash tables; clone of Unix ndbm) .$20 

NEW! PCAL Personal Calendar (generates PostScript calendar for any month or year, lots of options, personalization file for your dates & schedule) $20 

Unix/386 

X-Winaows (client & server, shared library, Xlib, executables, XAW etc.; code is diffs on X11R4; TCP or same machine).$200 

Kyoto Common Lisp (Austin flavor, naturally, Version 1.530; includes GCC and Portable Common Loops (PCL)).$140 

GNU Emacs Version 18.55 (includes complete source & executables).$125 

Waffle BBS (interface to UUCP & B or C news; internal forums; files section; external processing; full USENET support).$120 

GNU C Compiler (gec) Version 1.39 (includes complete source & executables).$100 

ViewComp Spreadsheet (internal termcap; printer output; hardcopy docs).$80 

GNU Debugger (gdb) Version 3.5 (includes complete source & executables).$60 

RPC Pack (Sun’s RPC Version 4.0 and Tansport Independent RPQ includes Bernstein’s Unix Client-Server Program Interface (UCSPI)) . . $40 

Gillespie Pascal-to-C (many flavors of Pascal handled; readable & maintainable output).$25 

Gosling Spreadsheet Pack (variants of the 1982 Gosling spreadsheet including PubliCalc and SC version 6.10; 1 MS-DOS variant) .$25 

NEW! PDKSH (Public Domain Korn Shell).$20 

The Austin Code Works Voice: (512) 258-0785 

11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1342 

Austin, Texas 78750-3587 USA E-mail: info@acw.com 
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WE HAVE AN OBJECTIVE 
POINT OF VIEW 


...with the Turbo Vision Development Toolkit for Turbo Pascal 
And, Turbo Vision for C++! 


We view traditional programming that requires recompilation to see changes to the program 
interface in a completely new and different way! Turbo Vision Development Toolkit lets you 
interactively create or change dialog boxes, menus and string lists in the Turbo Vision application 
framework. You can use the Resource Editor to develop and see Turbo Vision interface objects 
exactly as they will appear in your final application. The Resource Editor 
saves the objects to a resource file that can be loaded into your application 
with a single constructor call. 

The Toolkit also includes a utility to translate your resource files into Windows 
resource script files. This makes it easier to port your Turbo Vision applica¬ 
tions to Windows. 

An ongoing objective... 

We couldn’t and didn’t stop with just powerful utilities. We’ve built a number of 
objects that make your development easier and your applications more bullet¬ 
proof. Just some of these objects are an Enhanced Help Facility to display 
context-specific help information; a Memory Monitor to record and display 
memory usage; an Event Monitor to display all or selected events processed by 
Turbo Vision. 



These objects are especially useful during program development and debugging, and we’ve made 
it easy for the objects to be added to or removed from your application with a single statement. 

And, there's more... 


Of course, the Turbo Vision Development Toolkit comes with a comprehensive Reference 
Manual and Tutorial. The source code for all objects and utilities is included. 




BLAISE COMPUTING INC. 


July 1992 


Consider our point of view. 


The Turbo Vision Development Toolkit supports Turbo Vision applications in 
Pascal or C++ and costs just $169. We’re so convinced that you’ll find these utilities 
and objects essential that if during the first 60 days you’re not completely 
satisfied, we’ll refund your money. No questions asked! 


Call our order department toll free (800) 333-8087! 
Or, by fax, (510) 540-1938. 


819 Bancroft Way Berkeley, California 94710 (510)540-5441 


Trademarks are property of their respective holders. 
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From 

the Editor 


I still haven’t had a chance to play with half of the new API functions in Windows 
3.1 and yet the next generation of Windows is nearly upon us: Windows NT. If 
Microsoft stays on schedule, a couple of thousand of us will get a Windows NT beta 
(okay, technically they are calling it the “Microsoft Win32 Software Development Kit 
for Windows NT") at the July Win32 conference, lots more will receive beta copies by 
fall, and the final product will roll out at the end of the year. As I write this, how¬ 
ever, Windows NT is mostly visible in magazine articles. That’s the way it always is 
when a big new software product comes out; you first hear about it in authoritative 
articles that sound like the authors have already been using the product for years. 

Did you ever wonder where all these “instant experts” come from? After all, the 
real experts are usually too busy trying to get the product out the door to write 
articles about it. Well, in the case of Windows NT, I happen to know the answer. 
Back before I got into the magazine business, I got paid to do a few hours of 
technical reviewing on a Microsoft Press book being written by Helen Custer, of the 
Windows NT development group, called Inside Windows NT. Like at least a few 
hundred other people, I became an “instant expert" on Windows NT by reading 
drafts of this book. Now, I am happy to get a chance to feature material based on 
this book in Windows/DOS Developer's Journal; I just wish Microsoft had a similar 
book on the design of DOS Windows. 

Is Windows NT going to be an OS/2 killer? A UNIX killer? Will it even survive? Your 
guess is as good as anyone's. What I can say for sure is that the design of Windows 
NT will bring joy to any engineer’s heart. After moving from mainframes to UNIX to 
DOS, I look forward to finally moving back up to an operating system with all sorts 
of lovely gadgets to play with, including multithreading, symmetric multiprocessing 
(if I can afford the hardwarel), asynchronous I/O, security, multiple environments, 
and more. We don't have the space to cover as much ground as well as the book 
does, but I hope this month’s article on Windows NT’s architecture gives you a feel 
for what’s inside this new operating system. 

If you are attending the Win32 conference, look me up. I will be going to lectures 
(some will be given by the real experts), trying to become an "instant expert” on 
Win32s, talking to prospective authors, and looking at the pretty colors on my free 
Microsoft Win32 SDK CD-ROM. I’ll have one of those rare, limited-edition, one-size- 
fits-all, Windows/DOS Developer’s Journal T-shirts in my backpack for the first reader 
who spots me. 

Ron Burk, Editor 

'ft-*'**' — 
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Mark E. Peterson 


Memory Management Issues 

Memory managers in high-level languages such as C insu¬ 
late programmers from having to deal with the often slow 
and unsophisticated interface provided by the operating sys¬ 
tem. Any general-purpose memory manager performs the 
two basic functions, allocation and freeing; most of them also 
handle reallocation (resizing an allocated block) and provide 
internal algorithms that deal with memory fragmentation. 
Allocation is fairly straightforward: the memory manager 
must be able to supply a memory block of a specific size at the request of 
the application. It is useful for the allocator to add a few extra bytes to the 
block and store the size of the block there, so that the application does not 
have to pass the size back when the block is freed. 


One of the more obvious deficiencies of Windows 3.x is 
memory management - specifically, the limitations imposed 
by the global functions that allocate, reallocate, and free 
memory. These limitations make GlobalAlloc(), GlobalRe- 
Alloc(), and GlobalFreef), the three functions that perform 
most of Windows’ memory services, unsuitable for most ap¬ 
plications. (Versions of these three functions are also provided 
for the local - 64Kb limit - heap, but it is the global functions 
that access the multimegabyte heap available in standard- 
and enhanced-mode windows.) 

Evidently, these functions were not intended to be used 
for general-purpose memory management, since Windows al¬ 
lows only about 8,000 global memory blocks at any one time. 
This is a system-wide limitation, so the number of blocks 
available to your application will be 8,000 minus the amount 
used by all other currently running applications (including 
Windows itself). Another significant disadvantage is that every 
memory block has up to 32 bytes of overhead associated 
with it. While this is not in itself a huge amount, for small 
allocations an application could use twice as much memory 
as it needs. The last big drawback is speed: memory manage¬ 
ment with the SDK functions is up to 10 times slower than 
with a competent subsegment allocator. 


WINMEM: 

An Efficient Subsegment 
Memory Allocator 
for Windows 3.x 


July 1992 
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Freeing a block of memory is more complex. A competent 
memory manager keeps a list of free blocks, then uses the list 
to attempt to fill allocation requests before requesting more 
memory from the operating system. 

As an application runs, it may make thousands of requests 
for memory, subsequently freeing those requested blocks. 
This causes the memory heap to fragment into alternating 
series of allocated and freed blocks of memory (see Figure 1). 
Fragmentation, in turn, can cause the application to run out of 
memory. The fragmented 100-byte heap in Figure 1 actually 
has 45 free bytes, but the allocator can only satisfy a request 
for 25 bytes. 


**L.__ _:___ 
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New Dazzle/VB image control! 
Just $99 until 8/1/92! 

Display realistic 256 color images in Visual Basic! Break VB’s 
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display custom control for VB. This means that you can get 
your Windows app started without programming! But when 
you need to program for greater control, you can! And til 
8/1/92 you can save $200 off Dazzle’s list price! Also math, 
financial and comms VB products available — call: 

800-447-9120 ext. 125 
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Of the many strategies for combat¬ 
ing heap fragmentation, two of the 
more important are garbage collection 
and coalescing free blocks. Garbage col¬ 
lection involves arranging blocks of 
memory in the heap to maximize the 
amount of free space. This strategy is 
impractical in languages such as C, 
where the application has direct 
pointers to memory. Coalescing free 
blocks, though less effective, can be 
used with languages like C. Coalescing 
can occur when a newly freed block 
has at least one other block immedi¬ 
ately adjacent to it. The new free block 
and the adjacent one are combined to 
form one large free block. For example, if an application freed 
the first used block in Figure 1, it would be combined with the 
two free blocks adjacent to it to form one 30-byte free block 
(see Figure 2). 

A subissue of memory management is reallocation, or 
resizing an already allocated block of memory. This operation 
may be performed by allocating new memory, copying the 
old block to the new memory, and freeing the old block. A 
more sophisticated approach is to attempt to resize the block 
in place, where possible. 

Implementation 

Listing 2, winmem.c, contains the C code for a configurable 
general-purpose memory manager. As shown, it is capable of 
managing 16,384 64Kb segments with up to 16,384 free 
blocks. It supports memory overwrite detection via pickets, 
and can operate under both Windows 3.x (3.0 real, standard, 
and enhanced mode) and DOS. (Windows 3.1 arrived the day 
before I submitted this article, so I was able to test with it 
only briefly.) 

Many memory managers maintain the housekeeping infor¬ 
mation necessary for allocated and free blocks as part of the 
actual memory block. I made the conscious decision to keep 
this information in separate memory segments as much as 
possible. Separating out the housekeeping information makes 
memory bugs much easier to find, thereby reducing the chan¬ 
ces of a memory bug trashing the heap information. 

The function Uin_Malloc() services all allocation requests. 
Uin_Malloc() first searches the free list (Free_List) to satisfy 
an allocation. If that fails, it attempts to satisfy the request 
from unused space in the segment list ( Seg_List). If that also 
fails, another segment is allocated from the operating system. 

Once a suitable block of free memory is located, Uin_Mal- 
loc() stores the length of the block at the beginning of the 
block. Each block then has sizeof(SIZETYPE) bytes of extra 
overhead. If the block was taken from the free list and is 
bigger than the requested amount, Uin_Malloc() splits the 
block and adds the new, smaller free block to the free list. 
Because of the requirement to store the length of the block 
with the allocation, each block must be sizeof(SIZE_TYPE) 
aligned. 

Uin_Free() provides the block freeing operation. 
Uin_Free() inserts the new free block in sorted order by ad¬ 
dress into the free list ( Free_List ). Maintaining the free list in 
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Table 1 




Zortech C++ 3.0 

Winmem Zortech Compile 

Borland C++ 3.0 

Winmem Borland Compile 

Windows 3.0 

10.38 

4.84 

4.01 

5.38 

Windows 3.1 

10.22 

4.83 

4.61 

5.32 



Performance Test Run Times (in Seconds) 



sorted order facilitates coalescing of free blocks. After a block 
is added to the free list, the blocks preceding and following it 
are checked for adjacency. Any blocks adjacent to the new 
block are coalesced with it to form a single larger block. 

As a concession to performance, all the routines that deal 
with the free list maintain information about the largest free 
block in the free list (Largest_Free_Idx, Largest_Free). In 
many cases this allows the allocator to avoid searching the 
free list. 

The other memory functions supplied in the code - 
Uin_Calloc(), Uin_Strdup(), and Uin_Realloc() - operate 
precisely as their standard C library counterparts. The function 
Ki l l_Mem_Mgr() releases all memory back to the operating 
system and should be called when the application is ready to 
terminate. 

One feature that sets this memory manager apart is 
debugging support. Despite the number of years C has been 
around and the number of bugs that occur due to memory 
overwrites, most commercial compilers offer little or no help 
in tracking down memory bugs. 

winmem.c incorporates a method of detecting memory 
overwrites via pickets. Pickets consist of a set of known bytes 
inserted immediately before and after a block of memory. 
When the memory manager is called with debugging support 
on, it walks the entire heap and checks the pickets on each 
block. If it finds a value other than the legal picket value in a 
place where a picket should be, the memory manager halts 
and reports the error. I have found this feature to be invalu¬ 
able. 

Of course, turning on debugging support has side effects: 
each memory block will be sizeof(PICKET_TYPE)*2 larger 
than normal, and the memory manager itself slows down by 
a factor of three or four. 

When operating under Windows, the memory manager 
uses GlobalAllocf) to request memory from the operating 
system. Each segment is then locked with Global Lock () and 
remains so for the life of the application. While locking allo¬ 
cated segments would seem to prevent Windows from 
moving segments around to increase free space, this is not 
the case. In standard and enhanced mode, Windows actually 
does rearrange locked blocks of memory, using the advanced 
features of the 286 and 386 processors. Contrary to what 
many manuals seem to say, locked blocks are only immov¬ 
able in real mode. 

Efficiency 

For purposes of compiler portability and ease of under¬ 
standing, I wrote the memory manager entirely in C. Surpris¬ 
ingly, Winmem's speed is competitive with Borland's Windows 


Listing 1 (winmem.h) 

lifndef WINMEM_HPP 
#define WINMEM_HPP 
Idefine SGN_SIZE_TYPE int 

Idefine SIZEJTYPE unsigned SGN_SIZE_TYPE 

Idefine PTR_DIST far 

void Win_Free(void PTR_DIST *); 
void PTR_DIST *Win_Malloc(SIZE_TYPE); 
void PTR_DIST *Win_Realloc(void PTR_DIST ‘Block, 
SIZEJTYPE Size); 
void PTR_DI$T *Win_Calloc(SIZE_TYPE N_Elem, 
SIZEJTYPE Size); 

char PTR_DIST *Win_Strdup(char PTR_DIST *); 
lendif 

/* End of File */ 


memory manager and beats Zortech’s hands down. There are 
some small bottlenecks in the code, most of them dealing 
with searching the free list. Some hand-tuning in assembler 
should bring Winmem in ahead of Borland as well. 
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The biggest bottleneck is the loop in function Uin_Free() 
that searches for the insertion point of a new free block into 
the free list. 

for (i=0; i<Num_Free; i++) 

if (PN(B1k)<PN(Free_List[i])) 
break; 

As the free list is in sorted order, the insertion point could be 
found with a binary search, rather than the linear one. Recod¬ 
ing this segment in assembly would also be helpful. 


To get an idea of the performance of this memory 
manager vs. commercial compilers, I wrote a short test ap¬ 
plication that randomly allocates and frees blocks. Table 1 
summarizes the results. 

The tests were run under the 386 enhanced mode of Win¬ 
dows 3.0 and 3.1. The test program was compiled four times. 
Two compiles used the Windows malloc and free functions 
supplied with the Borland and Zortech compilers. The other 
two compiles used Uinmem with each compiler. All "safe” op¬ 
timizations were enabled with both compilers and used large 
model. The test machine was a 33-MHz Gateway 486. The test 


Listing 2 (winmem.c) 


linclude <stdio.h> 
linclude <stdlib.h> 
linclude <string.h> 
linclude "winmem.h* 

Idefine MSWIN 
/* Idefine MEMDEBUG */ 

Idefine PICKET TYPE long 

Idefine PICKET _ VAL 0x89abcdefl 

Idefine FREE_BLK_ELEMS 1000 

Idefine min(a,b) (((a) < (b)) ? (a) : (b)) 

Idefine BLK_LEN(x) (*((SIZE_TYPE *) (x))) 

Idefine PN(P) ((unsigned long) (P)) 

lifdef MSWIN 

/* Allocator definitions for Windows. */ 

Idefine PAGE_SIZE 65535u 

linclude <windows.h> 

static void Err_Handler(char PTR_DIST *M) 

{ /* Report an error to the screen */ 

MessageBox(GetFocus(),M, M FATAL",MB_0K); 
PostQuitMessage(l); 

} 

static void Sys_Dealloc(HANDLE H.void PTR_DIST *P) 

{ /* Return memory to the OS. */ 

GlobalUnlock(H); 
if (GlobalFree(H)) 

Err Handler("Error freeing block."); 

} 

static void PTR DIST *Sys Alloc(HANDLE *H, 
SIZE_TYPE S) 

{ /* Request memory from OS. */ 
void PTR DIST *P; 

if (((*Hj=Gl obal A11oc(GMEM_M0VEAB L E,S))==NULL) 

Err Handler("0ut of memory."); 

If ((P=G1obalLock(*H))==NULL) 

Err_Handler("Lock Error."); 
return P; 

} 

static void PTR DIST *Sys_Realloc(HANDLE ‘H, 

void PTR_DIST ‘P,SIZE_TYPE S) 

{ /* Resize a block of system memory. */ 
if (!(*H)) 

return Sys Alloc(H.S); 

G1obalUniock(*H); 

(*H)=G1obalReAl1oc(*H,S,GMEM MOVEABLE); 
if (!(*H)) 

Err Handler("0ut of memory."); 

P=Globallock(*H); 
if (!P) 

Err_Handler(“Lock error."); 
return P; 

) 

/* End of allocator definitions for Windows. */ 
#else 

/* Allocator definitions for DOS. */ 

Idefine PAGE SIZE 65531u 

Idefine HANDLE void PTR_DIST * 

static void Err_Handler(char PTR_DIST *M) 

{ /* Report an error to the screen */ 
printf(M); 
exit(l); 

) 

static void Sys_Deal1oc(HANDLE H.void PTR_0IST *P) 

{ /* Return memory to the OS. */ 
free(P); 

) 

static void PTR DIST *Sys Realloc(HANDLE *H, 

void PTR_DIST *P,SIZE_TYPE S) 
{ /* Resize a block of system memory. */ 

P=realloc(P,S); 


(*H)=P; 
if (!P) 

Err Handler("0ut of memory."); 
return P; 

) 

static void PTR DIST *Sys Alloc(HANDLE *H, 

SIZE_TYPE S) 

( /* Request memory from OS. */ 
void PTRJIST *P; 

P»mallocjs); 

(*H)=P; 
if (!P) 

Err_Handler("Out of memory."); 
return P; 

} 

/* End of allocator definitions for DOS. */ 
lendlf 

struct Seg_Info 

{ /* Housekeeping info for memory from OS. */ 

HANDLE Glbl Mem; 

SIZE TYPE Alloc_Bytes; 
char”PTR_DIST *Free_Addr; 
char PTR DIST *Base_Addr; 

}; 

static SIZE_TYPE Num_Segs; 

static HANDLE Seg_Handle; 

static struct Seg_Info *Seg_List; 

static SIZE_TYPE Num_Free; 

static SIZE TYPE Largest Free; 

static SGNJIZEJYPE Largest_Free_Idx=-l; 

static HANDLE Free Handle; 

static char PTR_DIST * PTR_DIST *Free_L1st; 

void Kill_Mem_Mgr(void) 

{ /* Release all memory back to OS. */ 

SGN_SIZE_TYPE 1; 

for (i=0; i<Num_Segs; i++) 

Sys_Dealloc(Seg_List[i].Glbl_Mem, 

Seg_List[i].Base”Addr); 

if (Num_Segs) 

Sys_Dealloc(Seg_Handle,Seg_List); 

} 

lifdef MEMDEBUG 

static void Mark_Block(char PTR_DIST *Ret) 

{ /* Put pickets around a memory block. *f 
if (BLK_LEN(Ret)>=(sizeof(SIZE TYPE)+ 

sizeof(PICKET TYPE)*2)) 

{ 

‘((PICKET TYPE *) (Ret+sizeof(SIZE TYPE)))= 

PICKET VAL; 

‘((PICKET TYPE *) (Ret+BLK LEN(Ret)- 

sizeof(PICKET TYPE)))=PICKET VAL; 

} 

} 

static void Validate_Pickets(char PTR_DIST *Cur_Addr) 
{ /* Check the pickets on a memory block. */ 
if (BLK_LEN(Cur Addr)>=(sizeof(SIZE TYPE)+ 

sizeof(PICKET VAL)*2)) 

{ 

if (‘((PICKET TYPE *) 

(Cur_Addr+sizeof (SIZE_TYPE)))! "PICKETJAL) 
Err_Handler("Leading picket error."); 
if (‘((PICKET TYPE *) (Cur Addr+ 

BLK LEN(Cur_Addr)-sizeof(PICKET TYPE)))!= 
PICKET_VAL) 

Err Handler("Trailing picket error."); 

} 

} 

static void Check_Heap(void) 

{ /* Check the pickets on the entire heap. */ 
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application performed roughly 25,000 mallocs and frees, and 
is written to force the memory manager to search the free 
list. (If you wish you may download the test program [and 
Winmem] from my BBS; it will be prominently visible on the 
BBS main menu.) 

Seeing the dismal performance of the Zortech memory 
manager, I did some investigation in their library source code. 
Apparently, the Zortech manager maintains one GlobalAlloc 
segment for the entire heap. When the manager needs more 
memory, it GlobalReallocs either exactly the extra amount it 
needs or 1Kb extra, whichever is larger. What this means is 


that, on the average, the Zortech routines do a GlobalRealloc 
for every 1,024 bytes of mallocs. This performance effectively 
demonstrates the problems of relying too heavily on the 
GlobalXXXXX functions. 

Another interesting bit of information surfaced when I ran 
the test program. Both Zortech and Borland compilers seemed 
reluctant to search the free list to fill a memory request. Often 
they would fill a request with a new block of unallocated 
memory despite the fact that there was a big enough block 
on the free list. Although this approach is faster, it can ag¬ 
gravate the problem of fragmentation. Winmem maintained a 


Listing 2 - Cont’d 


SGN_SIZE_TYPE i; 

for (i=0; i<Num Segs; i++) 

{ 

SIZE_TYPE Proc_Bytes=0; 

char PTRJMST *Cur_Addr=Seg_List[i].Base_Addr; 
while (Proc_Bytes<Seg_List[1].Alloc Bytes) 

{ 

Validate_Pickets(Cur_Addr); 

Proc Bytes+=BLK LEN(Cur Addr); 
Cur_Addr+=BLK_LEN(Cur_Addr); 

} 

if (Proc_Bytes!=Seg_List[i].Alloc_Bytes) 

Err Handler("Heap length error."); 

} 

} 

lendif 

static void Add_Free(char PTR_DIST *Itm) 

{ /* Add a free block to the free list. */ 

Num Free++; 

if f(Num Free%FREE BLK ELEMS)==1) 

Free_Llst=(char PTR_DIST * PTR_DIST *) 

Sys Real 1oc(&Free_Handle,Free_List, 

(Num Free+FREE_BLK_ELEMS-1)* 
sizeof(char PTR_DIST *)); 

Free_List[Num_Free-l]=Itm; 
if (Largest_Free Idx!=-1 && Largest_Free< 

BLK LEN(Itm)) 

{ 

Largest_Free=BLK_LEN(Itm); 

Largest Free Idx=Num Free-1; 

} 

} 

static void Delete_Free(SIZE_TYPE Pos) 

{ /* Delete an entry from the free list. */ 
if (Largest_Free_Idx>=0) 

{ 

if (Pos==Largest_Free_Idx) 

Largest_Free_Idx=-l; 
else if (Pos<Largest_Free_Idx) 

Largest_Free Idx-; 

i 

if (Num_Free==l) 

( 

Sys Dealloc(Free Handle,Free List); 

Free_List=NULL; “ 

Num_Free=0; 

Free_Handle=NULL; 

} 

else 

{ 

if (Pos!=(Num_Free-l)) 

memmove(Free List+Pos,Free List+Pos+1,(Num_Free- 
Pos-l)*sizeof(char PTR_DIST *)); 

Num Free-; 

if f(Num_Free%FREE_BLK ELEMS)==0) 

i 

Free_List=(char PTR_DIST * PTR_DIST *) 

Sys_Real1oc(&Free_Handl e,Free_Li st, 
Num~Free*sizeof(char PTR_DIST - *)); 
if (!Free_Handle || !Free_L1st) 

Err Handler(“0ut of memory."); 

) 

} 

} 

static void Insert Free(SIZE TYPE Pos, 

char’PTR_DIST *Item) 

{ /* Insert an entry into the free list. */ 
if (Largest_Free Idx!=-l) 

{ 


if (Largest Free<BLK_LEN(Item)) 

{ 

Largest_Free=BLK_LEN(Item); 
Largest_Free_Idx=Pos; 

} 

else if (Pos<=Largest_Free_Idx) 

Largest Free Idx++; 

} 

Add_Free(Item); 
if "(Pos==(Num_Free-l)) 
return; 

menmove (Free_Li st+Pos+1, Free_Li st+Pos, 

(Num_Free-Pos-l)*sizeof(char PTR_DIST *)); 
Free List[Pos]=Item; 

} 

static SGN_SIZE_TYPE Search_Free(SIZE_TYPE Size) 

{ /* Search the free list for a block>=Size bytes */ 
SGN_SIZE_TYPE Largest_Pos,i; 

SIZE_TYPE Largest_Found=0,Blk_Size; 
if (iNum Free) 

{ 

Largest_Free_Idx=-l; 
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more compact and less fragmented heap than the manager 
supplied with either commercial compiler. 

One feature that Uinmem lacks is the ability to return a 
segment to the operating system when it is completely 
empty. Once Uin_Malloc() allocates a segment, it remains al¬ 
located to the application until Kill_Mem_Mgr() is called. This 
is a serious problem only if your application requires large 
amounts of memory periodically but needs a much smaller 
heap the rest of the time. To remedy this problem, you could 
check every time a block is freed to see if the segment the 
newly freed block is in is completely empty. If so, the seg¬ 
ment could then be returned to the operating system. 


Portability/Conversion Notes 

The Uinmem C source is compatible with the Borland C++ 3.0 
and Zortech C++ 3.0 compilers in both C and C++ mode in the 
large model. To compile winmem for DOS instead of Windows, 
simply comment out tdefine MSUIN. 

If you configure Uinmem with the # defines to handle 
blocks greater than 64Kb, you may need to change PTR_D1ST 
to huge as well as supply huge versions of memmove and 
memcpy. 

Uinmem can be used as the allocator/deallocater for new 
and delete in C++. You merely need to overload the global 
new and delete operators as follows: 


Listing 2 - Cont’d 

Largest_Free=Largest_Found; 
Largest_Free_Idx«Largest_Pos; 
return -1; 

) 

return 1; 

} 

static void Create_Seg(void) 

{ /* Get a new Seg from the OS, add it to Seg_List */ 
struct Seg Info New_Seg; 

New_Seg.Base_Addr*(char PTR_DIST *) 

Sys_A11oc(&New_Seg.G1b1_Mem,PAG E_SIZ E); 
New_Seg.Free_Addr*New_Seg.Base_Addr; 

New_Seg.A11ocBytes-0; 

Num_Segs++; 

Seg_List«(struct Seg_Info *) Sys_Realloc(&Seg_Handle 
Seg_List,Num_Segs*sizeof(struct Seg_Info)); 
Seg_List[Num_Segs-l]*New_Seg; 

} 

void PTR_DIST *Win_Malloc(SIZE_TYPE Bytes) 

{ /* Allocate a block Bytes big. */ 
char PTR_DIST *Ret,PTR DIST *Cur_Free; 

SGN_SIZE _ TYPE i,Found_Pos; 

SIZE TYPE Reqjytes-Bytes; 

Bytes+«sizeof(SIZETYPE); 
if (Bytes%sizeof(SIZE_TYPE)) 

Bytes+*sizeof(SIZE_TYPE)-(Bytes*sizeof(SIZE_TYPE)); 
lifdef MEMDEBUG 
Bytes+-sizeof(PICKET_TYPE)*2; 

Check_Heap(); 
lendif 

if (Bytes<Req_Bytes || Bytes>PAGE_SIZE) 
return NULL! 

Found_Pos*Search_Free(Bytes); 
if (Found_Pos>-0j 
{ 

Cur_Free*Free_List[Found_Pos]; 
if (BLK_LEN(Cur_Free)>Bytes) 

{ 

Largest_Free_Idx«-l; 

Free_List[Found_Pos]+*Bytes; 

BLKJ.EN(Free_List[Found_Pos])*BLK_LEN(Cur_Free)- 

"Bytes; 

lifdef MEMDEBUG 

Mark_Block(Free_List[Found_Pos]); 
lendif 

} 

else 

Delete_Free(Found_Pos); 

BLK_LEN(Cur Free)-Bytes; 
lifdef MEMDEBUG 
Mark_Block(Cur_Free); 
return Cur Free+sizeof(SIZE_TYPE)+ 
sizeof(PICKET_TYPE); 

lelse 

return Cur_Free+sizeof(SIZE_TYPE); 
lendif 

} 

for (i*Num_Segs-l; i>-0; i-) 
if ((PAGE_SIZE-Seg_List[i].A1loc_Bytes)>Bytes) 
break; 
if (i<0) 

{ 

Create_Seg(); 
i-Num Segs-1; 

} 

Ret=Seg_List[i].Free_Addr; 

BLK_LENlRet)*Bytes; " 

Seg_List[i].Free_Addr+*Bytes; 

Seg_List[i],A1 loc_Bytes+*Bytes; 
lifdef MEMDEBUG 
Mark_Block(Ret); 

return Ret+sizeof(SIZE_TYPE)+sizeof(PICKETTYPE); 
lelse 
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return -1; 

} 

if (Largest Free_Idx>-0) 

{ 

if (Size<*Largest_Free) 
return Largest_Free_Idx; 
else 

return -1; 

1 

for (i-0; i<Num_Free; i++) 

{ 

B1k_Size*BLK_LEN(Free_List[i]); 
if (Blk_Size>-Size) 
break; 

else if (Largest_Found<Blk_Size) 

{ 

Largest_Found*Blk_Size; 
Largest_Pos«i; 

} 

} 

if (i”Num_Free) 

( 
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void ‘operator new(unsigned x) 

{ return Win_Malloc(x); } 
void operator delete(void *p) 

{ Win_Free(p); } 

Keep in mind that if you have overloaded new and delete in 
any object definitions, you will need to insert similar code 
there. 


Conclusion 

Having a well-designed and efficient memory manager is 
essential to quality applications. In languages like C, memory 
debugging capabilities can save a deadline. Relying on the 
memory management provided with an operating system or 
compiler can often be a mistake. 

If you are interested in studying this problem further, most 
good books on data structures and algorithms have chapters 
on memory management (see Aho, Hopcroft, and Ullman, Data 
Structures and Algorithms, Addison Wesley, for example). □ 


return Ret+sizeof(SIZE_TYPE); 

#endif 

} 

void Win_Free(void PTR_DIST ‘Block) 

{ /* Free a Win_Malloc block. */ 

SGN SIZE TYPE~i; 

char PTRDIST *Blk-(char PTRDIST *) Block; 
lifdef MEMDEBUG 
if (lBlock) 

{ 

printf("Attempt to free NULL Block.\n"); 
exit(l); 

} 

Blk—sizeof(SIZE_TYPE)+sizeof(PICKET TYPE); 

Validate_Pickets(B1k); 

Check_Heap(); 

lelse 

Blk—sizeof(SIZETYPE); 
lendif 

for (i-0; i<Num_Free; i++) 
if (PN(B1k)<PN(FreeList[i])) 
break; 

lifdef MEMDEBUG 

if (i && PN(Blk)--PN(Free_List[i-l])) 

Err_Handler(“Block freed twice."); 
lendif 

if (i<Num_Free) 

Insert Free(i.Blk); 
else 

AddFree(Blk); 

if (i) 

{ 

char PTR_DIST *Prev-Free_List[i-l]; 
if ((PN(Prev)+BLK_LEN(Prev))«PN(B1 k)) 

( 

BLK_LEN(Prev)+*BLK_LEN(Blk); 

Delete_Free(i); 
i-; 

lifdef MEMDEBUG 
Mark_Block(Prev); 
lendif 

) 

} 

if {(1+l)<Num_Free) 

( 

char PTRJ1IST *Prev=Free_List[i]; 

Blk-Free List[1+1]; 

i f ((PN(Pi-ev)+BLK LEN(Prev))—PN(B1 k)) 

( 

BLKJ.EN(Prev)+=BIK_LEN(B1 k): 

Delete Free(i+1); 
lifdef _ MEMOEBUG 
Mark Block(Prev); 
lendif” 

) 

} 

) 

void PTR DIST *Win_Realloc(void PTR_DIST *Blk, 

SIZE_TYPE NewSize) 

{ /* Resize a Win_Malloc block. */ 
void PTR_DIST *Ptr-Win Malloc(New Size); 

SIZE_TYPE Old Size; 
if (Blk) 

( 

lifdef MEMDEBUG 

01d_Size*BLK_LEN(((char PTR_0IST *) B1 k)- 

sizeof(SIZE_TYPE)-sizeof(PICKET TYPE))- 
sizeof(SIZE~TYPE)-sizeof(PICKET~TYPE)*2; 

lelse 

01d_Size=BLK_LEN(((char PTR_DIST *) Blk)- 

sizeof(SIZE_TYPE))-sizeof(SIZE_TYPE); 

lendif 

memcpy(Ptr,Blk,min(01d_Size,New_Size)); 


Listing 2 - Cont’d 


Win_Free(Blk); 

} 

return Ptr; 

) 

void PTR_DIST *Win_Calloc(SIZE_TYPE n.SIZETYPE size) 
{ /* Duplicates standard function calloc. */ 
void PTR_DIST *Ptr*Win_Malloc(n*size); 
memset(Ptr,0,n*size); 
return Ptr; 

) 

char PTR_DIST ‘Win_Strdup(char PTR_DIST ‘s) 

{ /* Duplicates standard function strdup. */ 
char PTR_DIST *Ptr«(char PTRDIST *) 

Win_Malloc(strlen(s)+l); 

strcpy(Ptr.s); 
return Ptr; 

} 

/* End of File •/ 
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Inside Windows NT: 

An Introduction 


Helen K. Custer 

This article was prepared by the Windows/DOS Developer’s 
Journal editorial staff and Helen Custer, and is largely based on 
her forthcoming book Inside Windows NT, which will be avail¬ 
able from Microsoft Press in late 1992. Though this article 
reflects the current state of Windows NT, no part of it should 
be construed as a commitment on the part of Microsoft Cor¬ 
poration. 

In the fall of 1988, Microsoft hired Dave Cutler to lead a 
new software development effort: to create Microsoft's 
operating system for the '90s. Dave came from Digital Equip¬ 
ment Corporation, where he spent 17 years developing a 
number of operating sytems and compilers, including the 
VAX/VMS and the RSX-11M operating systems, and the VAX 
PL/1 and VAX C compilers. Upon his arrival at Microsoft, Dave 
quickly assembled a team of engineers to design Microsoft's 
"New Technology (NT)” operating system. 

Initially, the new operating system was dubbed "NT OS/2” 
ard was variously viewed by the press as the workstation 
version of OS/2, the portable version of OS/2, or just plain OS/2 
v3.0. All of these views missed the point that, far from being a 



derivative of OS/2, NT was a brand new architecture, and OS/2 
was just one of several operating system interfaces NT was 
designed to support. In fact, using some concepts borrowed 
from the Mach operating system (which was designed to sup¬ 
port multiple versions of UNIX simultaneously), NT was 
designed from the beginning to support OS/2, POSIX, 16-bit 
Windows (Windows 3.x applications), DOS, and Win32 (the new 
32-bit windows API designed to span 16- and 32-bit machine 
architectures). Figure 1 provides an overview of this new ar¬ 
chitecture. 

The advantage of NT's chameleon-like design became clear 
when, well into the development of the new operating sys¬ 
tem, Windows 3.0 became a large market success. When 
Microsoft decided to shift its development efforts from OS/2 to 
the more successful Windows, relatively little work was lost. 
The name changed from "NT OS/2” to “Windows NT” and the 
module providing the Win32 interface became a higher 
priority than the module providing the OS/2 interface. 

Until now, Windows NT has only been available in a pre¬ 
beta form to a limited number of developers. However, since 
the finished product is targeted for the end of 1992, you can 
expect to see a beta program begin this summer and widen 
during the fall. Since Windows NT will present only its Win¬ 
dows face to most beta testers, some will not guess what is 
going on "under the hood.” While Windows NT is the worksta¬ 
tion version of Windows, the portable version of Windows, 
and Microsoft's high-end Windows operating system, these 
labels are misleading. Everything beneath the user interface is 
new. 

The goal of this article is to introduce you to the underly¬ 
ing architecture of Windows NT, since programmers often 
benefit by having an accurate mental model of the operating 
system they are writing for. The first part of the article 
provides a short overview of the operating system's design 
features. The second part traces a call to a Win32 API function 
under Windows NT, to illustrate the vast differences between 
existing Windows and the client/server architecture of Win¬ 
dows NT. 


Helen Custer has worked for the last three years in Microsoft's 
Windows NT development group, chronicling the emerging 
design of Windows NT. 
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Design Features 

To appreciate the scope of this new operating system, you 
must understand the ambitious set of goals its designers 
began with. This section discusses the design goals that will 
ultimately have the greatest impact on developers. 

Portability 

Windows NT is designed to be portable; the alpha version 
already runs on PCs and workstations based on both the Intel 
(i386/i486) and MIPS (R3000/R4000) processors. The goal of por¬ 
tability represents a major departure in the PC world, since 
both DOS and OS/2 were written largely in assembly language, 
without regard to 80x86 dependencies. The portability of Win¬ 
dows NT will carry thousands of DOS and Windows applica¬ 
tions into new markets, and, with the Win32 API, developers 
will be able to write 32-bit Windows applications compatible 
with both PCs and workstations. 

Protected Subsystems 

As mentioned earlier, the system’s design allows Windows 
NT to offer multiple operating system environments. It does 
this by way of protected subsystems, modules which run in 
user mode, but which directly access the NT Executive's ex¬ 
tensive set of operating system services. One kind of 
protected subsystem, the environment subsystem, provides a 


particular operating system environment such as Win32, 16- 
bit Windows, DOS, POSIX, or OS/2. Windows NT runs these en¬ 
vironment subsystems simultaneously, which is what allows 
you to run your existing Windows applications alongside ap¬ 
plications written specifically for the new Win32 API. 

The flexibility of protected subsystems may contribute 
greatly to the long-term viability of this new operating sys¬ 
tem. As noted earlier, the operating system has already sur¬ 
vived the change from NT OS/2 to Windows NT with ease. 

Compatibility 

An area of compelling interest to developers and users 
alike is backward compatibility. Considering how little Win¬ 
dows NT resembles either Windows or DOS internally, it 
provides a striking degree of backward compatibility with 
both environments. Probably the most surprising feature is 
Windows NT’s offer of binary compatibility for DOS and 16-bit 
Windows applications - even on non-Intel architectures. That 
means you can place your DOS executable on a floppy, insert 
it in a MIPS workstation running Windows NT, and execute it. 
Emulating 80x86 instructions on a RISC computer may sound 
like a slow proposition. However, the MIPS emulator 
(developed by Insignia Solutions, Ltd.) is quite advanced and 
can actually translate 80x86 code into native machine code, 
on-the-fly. 


Figure 1 
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Figure 2 


asymmetric multi-processing (ASMP) 




Symmetric versus Asymmetric Multiprocessing 


A more difficult emulation problem 
arises in all the many ways that PC 
software is tied directly to the 
hardware. The "line in the sand” is still 
being drawn, so it is impossible right 
now to list exactly which nasty situa¬ 
tions the emulator will or will not hand¬ 
le. if your DOS program depends upon 
non-standard hardware or undocu¬ 
mented tricks, it will probably not run 
on Windows NT. On the other hand, 
you can expect that common hardware 
dependencies, such as writing directly 
to a video device for fast text display, 
will be supported. 

Supporting current Windows 3.x ap¬ 
plications also presents problems. Both 
Windows 3.0 and Windows 3.1 use a 
single, global address space, leaving 
your application free to destroy other 
applications or even Windows itself. 
That is not acceptable for Windows NT, 
since it is designed to meet the 
government's C2 security rating. There¬ 
fore, Windows NT has to confine Win¬ 
dows 16-bit applications to their own 
special “cage"; your 16-bit Windows ap¬ 
plication can still crash other 16-bit 
Windows applications running on Win¬ 
dows NT, but the operating system and 
Win32 applications remain secure. 

Although most PC developers care 
about DOS and Windows 3.x com¬ 
patibility, the initial release of Windows 
NT is also slated to support POSIX-com- 
pliant applications. It will also support 
OS/2 character-mode applications (but 
not Presentation Manager applications) 
in the first release. 

You can run your 16-bit Windows 
application as-is on Windows NT, but 


most developers will want to port their 
applications to the Win32 API. The 
majority of the Win32 API is compatible 
with Windows 3.1; it is simply the Win¬ 
dows 3.1 API expanded to 32 bits. Some 
changes were required for security, to 
remove CPU dependencies, or to take 
advantage of Windows NT features such 
as multithreading, asynchronous I/O, 
and symmetric multiprocessing. 

Reliability 

An integral goal of Windows NT's 
design is to make sure that your ap¬ 
plication cannot crash the system, can¬ 
not crash other applications, and can al¬ 
ways be terminated by the user, no 
matter how ill-behaved it is. As men¬ 
tioned earlier, a Win32 process cannot 
modify other applications or the operat¬ 
ing system. Furthermore, the Windows 
NT executive protects itself even from 
environment subsystems. As user-mode 
“applications,” they have no access to 
system memory. 

PC programmers don't run into much 
security apart from the simple set of 
permissions that some network file sys¬ 
tems provide. In contrast, Windows NT 
uses object-based security to provide 
uniform access control to a variety of 
resources, not just files. The security 
features protect against both buggy ap¬ 
plications and malicious attacks. 
Another contribution to reliability is 
structured exception handling, which 
Windows NT uses internally and also of¬ 
fers to applications. Structured excep¬ 
tion handling gives your application a 
way to get control when errors occur 
and to handle them gracefully. 


Design Overview 

Windows NT is a complex operating 
system and no single model adequately 
describes it. Perhaps the best way to 
grasp the architecture is to look at it 
from several different perspectives - as 
a client/server system, an object-based 
system, and a “multi-everything” sys¬ 
tem. 

Client/server Architecture 

Figure 1 depicts Windows NT's 
client/server structure, a system ar¬ 
chitecture that may be unfamiliar to 
Windows programmers. As mentioned 
previously, each Win32 process runs in 
a private address space and cannot 
harm either the operating system or 
other processes. The Win32 subsystem, 
which implements Win32 API routines, 
runs in a separate process. Flow, then, 
does a Win32 process call the Win32 
protected subsystem, which is not even 
in the same address space? 

This is similar to the problems that 
designers of distributed computing sys¬ 
tems have already faced and solved. A 
standard solution to calling code that 
resides across a network on another 
machine is the Remote Procedure Call 
(RPC) facility; the calling program on 
Machine A packages up the function 
parameters and sends them in a packet 
across the network to Machine B, 
where the remote procedure performs 
the reverse procedure on the packet, 
executes the function, and sends the 
reply packet back to Machine A. Inter¬ 
nally, Windows NT uses a similar solu¬ 
tion, called Local Procedure Call (LPC). 

The client/server architecture creates 
more work for the operating system 
designer, especially to achieve an effi¬ 
cient implementation. Flowever, the 
benefits this structure provides make it 
worth the effort. From the operating 
system's viewpoint, it manages two 
kinds of data for processes: global and 
local data. Global data is essential for 
the operation of more than one 
process. For example, Windows main¬ 
tains a list of all the windows that cur¬ 
rently exist. If global data is accessible 
to your application, a bug could crash 
other applications or the operating sys¬ 
tem (by trashing a pointer in the win¬ 
dow list, for example). Local data, in con¬ 
trast, is specific to a particular process. For 
example, the operating system maintains 
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a file position for you for each file you 
open, but if you accidentally write over 
that data, it does not affect the operat¬ 
ing system or any other application. 

The client/server architecture 
provides an opportunity to keep global 
data out of harm's way in a separate 
address space. Windows 3.x does not 
use a client/server architecture and it 
takes full advantage of the efficiencies 
that a single address space offers. Win¬ 
dows NT, however, is aimed at higher- 
end machines and uses several im¬ 
plementation strategies to keep the 
cost of the client/server architecture 
low. Although a client/server architec¬ 
ture is a challenge to implement effi¬ 
ciently, the payback is an operating sys¬ 
tem that is immune to the wide variety 
of abuses that buggy applications can 
heap upon it. 

Object Model 

One reason operating systems are 
difficult to design and maintain is that 
they offer such a hodgepodge of ser¬ 
vices to the processes that they ex¬ 
ecute. The challenge is to find any 
uniformity in the operating system API 
functions, from device I/O, to file access, 
to interprocess communication. 

Windows NT partially solves this 
problem by adopting an object model 
to represent shared system resources. 
This object model allows it to treat 
diverse resources uniformly. 

For example, by protecting objects, 
Windows NT establishes a uniform view 
of security for all resources that two or 
more processes can share. Although 
you cannot access Windows NT objects 
directly, you indirectly access them 
each time you use a resource. Windows 
NT objects correspond to both per¬ 
manent resources, such as files, and 
temporary resources, such as shared 
memory. 

The Windows NT object model 
resembles the common model for ac¬ 
cessing files. Any object can have a 
name, just as all files have names. In 
fact, the hierarchical tree of file names 
is a subset of the global tree of Win¬ 
dows NT object names. Object names 
provide a uniform method for sharing 
resources. One process can create an 
object and place its name in the global 
object namespace, and a second 
process can open a handle to that ob¬ 
ject by specifying the object's name. 


This provides a single framework for 
handling files, named pipes, drive 
names, and other shared resources. 

"Multi-everything" 

Windows NT is multiuser, multitask¬ 
ing, multithreading, and multiprocessing. 
Unfortunately, many people disagree on 
the precise definitions of these terms, 
so it is worth detailing what they mean 
in Windows NT. 

“Multiuser’’ does not mean that you 
can hang five keyboards and VGA 
monitors off a single PC running Win¬ 
dows NT. Windows NT is multiuser in 
that it supports separate security for 
each logical user. Windows NT beta 
users may be surprised that they have 
to log on to their own machine and 
enter a password. Likewise, remote 
processes that access services on a 
Windows NT server must first log on to 
establish a session (a concept familiar to 
programmers who write SQL server ap¬ 
plications). Just as with a UNIX graphics 
workstation, Windows NT can provide 
different security for multiple users 
(even “users" that are actually remote 
processes), but only has one keyboard, 
one mouse, one screen, and one inter¬ 
active user at a time. 

“Multitasking” is probably the most 
muddied of this collection of terms. It 
means that Windows NT can run multi¬ 
ple programs and give the illusion that 
they are running simultaneously by 
switching control between them. More 
precisely, Windows NT offers “preemp¬ 
tive multitasking,” which means that, 
unlike Windows 3.x, it distributes CPU 
time among programs with or without 
their consent. Unfortunately, even the 
term “preemptive multitasking” leaves 
an important question unanswered. 
OS/2 offers preemptive multitasking, but 
a single PM application can lock up the 
machine simply by not surfacing to 
retrieve input messages. Windows NT 
solves this problem, as described later. 

“Multithreading” means the ability to 
support separate paths of execution 
within a single address space (i.e., 
process). Windows NT threads are not 
an add-on or special feature - the 
thread is the fundamental unit of ex¬ 
ecution in the operating system. While 
it is not too difficult for programmers to 
implement thread packages (even 
under operating systems like DOS, 
which do not provide multithreading 
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support), the operating system can offer much better thread 
services than an individual process can. For example, if a 
thread of your DOS program performs a disk read, nothing else 
will happen until that disk read completes; you have no way 
to execute another of your threads. Windows NT, however, is 
completely reentrant and it automatically executes another 
thread when the current thread is waiting for a device I/O to 
complete. 

“Multiprocessing" means the ability to use more than one 
CPU. The hardware world has been toying with multiple 
processor architecture designs for some time (a few multi-CPU 
PCs are even available), but without overwhelming success in 
the marketplace. Part of the problem is that software, as al¬ 
ways, has lagged behind hardware. Some of the more suc¬ 
cessful early efforts involved attempts to add multiprocessing 
capabilities to UNIX. The easiest architecture for this is shown 
in the left half of Figure 2 and is called asymmetric multi¬ 
processing (ASMP). 

The problem with ASMP is that work is not evenly dis¬ 
tributed across the separate CPUs. Users might reasonably ex¬ 
pect that a six-processor machine could run six programs as 
well as a three-processor machine could run three. Unfor¬ 
tunately, the operating system can become a bottleneck be¬ 
cause it can only run on a specific CPU on the machine. Al¬ 
though this restriction limits the scalability of the multiproces¬ 
sor architecture, it relieves the operating system architect of a 
great many synchronization problems, since the operating sys¬ 
tem only does one thing at a time. 
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The right half of Figure 2 shows the Windows NT design, 
which offers Symmetric Multiprocessing (SMP). With SMP, the 
NT Executive can execute on any CPU that is free, and even 
execute on more than one CPU at a time. Placing the burden 
of SMP support on the operating system takes a load off of 
the application developer. Since Windows NT handles the 
headaches of symmetric multiprocessing (SMP), any multi¬ 
processing machine running two or more Windows NT ap¬ 
plications benefits from the extra processors, without any spe¬ 
cial coding on the application developer's part. In addition, 
multithreaded applications such as the SQL server can actively 
exploit multiple processors. 

The Win32 Subsystem 

Ideally, each environment subsystem would have been in¬ 
dependent enough that the rest of the operating system 
could function without it. The POSIX and OS/2 environment 
subsystems are, in fact, optional modules. As Windows NT 
developed, however, the Win32 subsystem acquired a special 
status that makes it essential to the rest of the operating sys¬ 
tem. In particular, the Win32 subsystem maintains control of 
the screen, the keyboard, and the mouse; thus the other en¬ 
vironment subsystems depend on Win32 for services related 
to user input and display. This elevated status and the fact 
that Win32 has a much larger ready-made audience of 
programmers than the POSIX or OS/2 environment subsystems 
make it the item of most interest to programmers. 

Win32: API vs. Subsystem 

With terms like Windows, Win32, Windows NT, and Win32s 
being bandied about in different contexts, it is easy to get 
confused about what they all mean. For ease of discussion, I 
will use the term “DOS Windows” to refer to Windows 3.x or 
any of its successors that run as extensions to DOS. 

The most important term to understand is “Win32 API,” 
since it is the key to writing portable 32-bit Windows applica¬ 
tions. This new API will first appear as the programming inter¬ 
face to Windows NT. A subset of the Win32 API, known as 
WIN32S, will soon be available under DOS Windows. It will 
allow DOS Windows programmers to write 32-bit applications 
that run in the DOS Windows 16-bit environment. Later, DOS 
Windows will be enhanced with a more complete implemen¬ 
tation of the Win32 API. Although your application will be call¬ 
ing the same Win32 API functions under both DOS Windows 
and Windows NT, the underlying operating systems could not 
be more different. 

Porting to the Win32 API 

The Win32 API was born of the need for a single API for 
Windows programs that spans low- and high-end machines, 
both on Intel and non-Intel architectures. This new API is lar¬ 
gely compatible with the Windows 3.1 API, but some changes 
were necessary to remove nonportable assumptions and pro¬ 
vide access to new features. For instance, assuming that hand¬ 
les are 16 bits wide is nonportable. An example of a new 
capability occurs in the Win32 API GDI functions, which use a 
32-bit coordinate system for graphics rather than the 16-bit 
coordinate system of Windows 3.x. The switch to 32 bits also 
affects a variety of window messages. See the Win32 API 
prerelease specification for a detailed list. 
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A more subtle incompatibility between the Win32 API and 
Windows 3.1 solves a long-standing flaw of both Windows 
and OS/2 Presentation Manager. In both of these operating 
systems (even though OS/2 is technically preemptive), a single 
application can effectively lock up the machine by refusing to 
service its input queue. What is the problem? 

Figure 3 depicts the input model for Windows 3.x and 
Presentation Manager. The problem is that Windows 3.x and 
Presentation Manager assign keyboard and mouse messages 
to a specific application as they are read from the single 
shared system input queue - and only one application has 
the right to read the system input queue at any one time (the 
application with the "input focus”). Unfortunately, that means 
all other applications are at the mercy of the one with the 
input focus. If it does not service its input queue, then the 
user cannot deliver input to any other application, and the 
operating system appears to “hang." Presentation Manager 
programmers were supposed to use a separate thread to service 
the input queue so that this situation never arose-, in practice, 
they often didn't. 

Figure 4 shows the revised input model for the Win32 API. 
In this model, the operating system assigns the message to 
the correct program (thread within a program, to be precise) 
as soon as the keyboard or mouse event occurs. Each applica¬ 
tion has its own message queue which is independent of any 
other application's message queue. This has the downside of 
not being completely compatible with Windows 3.x, but it 
finally presents the user with an operating system that not 
only is preemptive and multitasking, but also acts like it. 

Tracing a Win32 Call 

Most PC programmers are familiar with the term 
“client/server architecture,” but usually only in the context of 
remote databases. Viewing the operating system as a server 
and your application as a client can take a little getting used 
to. So far, all you have seen are diagrams that claim that ap¬ 
plications communicate with Windows NT using messages 
rather than function calls. On the other hand, the Win32 API 
still looks like a set of function calls on the surface, so what is 
really going on? One way to get a feel for Windows NT's 
client/server architecture is to follow what happens when 
your application calls a Win32 API function under Windows NT. 

In Windows 3.x, you link your application with “import 
libraries" that contain the names of the available Windows 3.x 
functions. In the resulting . exe, the linker notes all the places 
that your code calls any of these functions, when you ex¬ 
ecute this program, the Windows loader dynamically stores 
the correct addresses in all of the places your code calls a 
Windows function. When your application finally calls a Win¬ 
dows API function, it is really not much different from calling 
one of your own functions. Execution continues on a single 
thread in a single address space on the same stack - the 
executing code just happens to belong to Windows rather 
than your application 

Figure 5 shows that this simple API call is handled in a 
radically different manner by windows NT. The remainder of 
this section traces the steps involved in a “simple” API call 
under Windows NT, using the Local Procedure Call (LPC) mes¬ 
sage-passing facility mentioned earlier. 


The Journey Begins 

Your call to the Win32 API function is really a DLL call, just 
as it would be under Windows 3.1. So, your call transfers con¬ 
trol to code that is still in your address space, still running the 
same thread. This DLL function, however, is just a stub. It 
transforms your function call into an LPC message packet and 
calls an NT Executive service to initiate an LPC to the Win32 


Figure 3 
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subsystem. This immediately leads to the question "How do 
you call an NT Executive service?" 

Operating system code is visible in your thread's address 
space (the top two gigabytes of virtual memory are reserved 
for the operating system), but you cannot just jump to it 
while you are in user mode. Instead, your thread calls a sys¬ 
tem service and the processor traps the call. Your thread 
begins executing in the kernel’s trap handler. At this point, the 
kernel (you really are in the NT kernel at this point, not just 
the NT Executive) copies your system service arguments from 
the thread's user-mode stack to a kernel-mode stack. 

Why does the kernel bother to move the arguments out of 
reach of your process? The kernel cannot just assume that 
those arguments will remain intact, since your process could 
have other threads (possibly even executing simultaneously 
on another processor) that modify the data while privileged 
code is still using it. One source of operating system “holes” 
(methods of subverting security) is any method of modifying 
data after it has passed the operating system’s security in¬ 
spection and before the operating system uses it to perform 
some privileged service. 

The kernel trap handler is a highly optimized assembly lan¬ 
guage routine that has to figure out why it was called and 
take the appropriate action. It could have been called for 
reasons other than to execute a system service (such as to 
handle a hardware exception). Now your thread is in kernel 
mode, but the trap handler still has to locate and call the NT 
Executive code to handle the particular system service you 
are requesting (an LPC, in this case). This works much like the 
standard 80x86 interrupt dispatch table-, each system service 
is assigned a unique integer, starting at zero, and the system 
service dispatch table contains a corresponding array of 
pointers to the correct system service functions in the NT Ex¬ 
ecutive. 


Control then transfers to the system 
service for sending an LPC message. The 
system service copies the message 
from your address space into the ad¬ 
dress space of the Win32 subsystem. 
Next, it notifies the Win32 subsystem 
that a message has been delivered. 
Finally, the system service waits for a 
reply message from the Win32 subsys¬ 
tem, which has the effect of suspending 
your thread's execution. A Win32 
thread that was waiting to service mes¬ 
sages “wakes up" and executes your re¬ 
quest. 

After the Win32 subsystem services 
your request and sends back a reply, 
your thread, which was waiting for a 
reply, wakes up. Since it was suspended 
inside system service code (still in ker¬ 
nel mode) it copies the reply message 
back to your address space, switches 
back to user mode and returns to the 
DLL stub. The DLL does whatever is 
necessary with the LPC reply to return 
data to you, the caller. Finally, your 
original function call to the Win32 API 

function returns. 

This is more work than even the Windows 3.x “thunk" call¬ 
ing sequence, but Windows NT takes a number of pains to 
make LPC as fast as possible without giving up the security of 
the client/server architecture. You don't have to understand 
LPC to call a Win32 API function, but knowing what goes on 
behind the scenes provides a conceptual framework for un¬ 
derstanding the scores of Win32 API functions. 

Summary 

Windows NT brings modern operating systems concepts to 
the PC. Whether you view it initially as simply a high-end en¬ 
vironment for Windows applications or as a brand new 
operating system to exploit, understanding the architecture 
will enhance your ability to write Windows NT applications. 
Next month, I will continue to explore the design of the Win32 
environment subsystem. □ 
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Advanced Power Management for DOS 

Victor R. Volkman 


Introduction 

Today's palmtop and notebook computers - tiny cousins of 
the barely luggable (30 lbs.) models built in the early 1980s - 
provide extraordinary capability. As powerful as they have be¬ 
come, though, they remain power-hungry - for electricity. As 
hardware designers struggle to get the maximum battery life 
out of portable computers, power-conserving CPUs, such as 
the Intel 80386SL, are an increasingly popular choice. Low- 
power CMOS CPUs, such as the AMD 80C286, are another alter¬ 
native. Of course, the CPU is just one part of the overall com¬ 
puter system. 

Additionally, modern software demands that portable com¬ 
puters have several megabytes of RAM, VGA resolution dis¬ 
plays, mice, and hard disks. This means that portables need 
more battery power every year. In January 1992, Intel and 
Microsoft jointly introduced the Advanced Power Management 
(APM) Specification, which defines a hardware and software 
interface for battery conservation. Now, software developers 
who follow the APM interface can help portable computer 
users greatly increase their battery life. 

The Intel-Microsoft APM specification provides hooks for 
"power-aware” DOS applications to help regulate battery life. 
The actual APM software interface may be provided in the 
ROM BIOS or enabled later via a TSR. Microsoft plans to release 
a Windows interface for APM later this spring. The APM for 
Windows will provide a message-based interface more 
amenable to Windows applications. However, the APM for 
Windows specification was not publicly available as of this 
writing. In the remainder of this article, I’ll outline the APM 
software interface and describe how your DOS applications 
can take advantage of it. 


APM Layers 

The APM specification formally defines three layers: System 
BIOS layer, Operating System layer, and Application layer (see 
Figure 1 for a typical APM layering configuration with com¬ 
munication links). The lowest layer in the hierarchy, the Sys¬ 
tem BIOS layer, is responsible for initiating actions resulting in 
power state transitions. For example, it knows the sequence 
of actions required to suspend the system and bring it back to 
life intart. The System BIOS level is implemented a little dif¬ 
ferently by each vendor. However, applications can ignore this 
fact because the Operating System layer shields them from 
implementation details. 


How to Get APM 

• APM Drivers for your portable: if you already have MS- 
DOS 5.00, then you might already have the power.exe 
TSR for APM. Otherwise, contact the manufacturer’s 
technical support department for more information. 
Depending on your computer, the APM may require 
some combination of firmware and driver upgrades. 

• APM for Windows 3.1: drivers are expected to be sup¬ 
plied as a minimal cost Software Driver Library (SDL) 
from Microsoft 

• APM documentation: as of this writing, the documenta¬ 
tion is more readily available from Microsoft than from 
Intel. Contact MS Developer Services at (800)227-4679 
to obtain a free copy of APM in the mail. □ 


Victor R. Volkman received a BS in Computer Science from Michigan Technological University. He has been a frequent contributor to 
the Windows/DOS Developer's Journal since 1990. He is currently employed as Software Engineer at Cimage Corporation of Ann 
Arbor, Michigan. He can be reached directly at the HAL 9000 BBS (313) 663-4173 or as vrv@cimage.com on Usenet 
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The Operating System (OS) layer is responsible for the ap¬ 
plication-level interface to APM functionality. The APM 
specification identifies three primary responsibilites for the OS: 
acting as the intermediary between applications and System 
BIOS, arbitrating application APM calls in a multitasking en¬ 
vironment, and identifying power-saving opportunities not ap¬ 
parent at the Application layer. The OS layer appears through 
an INT 15h interface for DOS applications and through a DLL 
interface to Windows 3.1 applications. This layer switches into 
a power-saving state when it observes that all applications 
are idle. 

Last, the Application layer provides the one of the best 
opportunities for efficient and effective control of power. Al¬ 
though applications are not required to be APM-aware, those 
that are can contribute significantly to power conservation. 
First, an APM-aware application can monitor its own activity 
and shift into a low-power state when it is idle. Second, APM 
allows an application to selectively shut down system com¬ 
ponents (e.g., serial and parallel ports) it is not actively using. 

APM States and Transitions 

The APM model formally defines four distinct power states: 
Ready, Stand-by, Off, and Suspended. The first three can be 
applied to any system component or the entire system. The 
Suspended state is a special low-power condition that must 
be applied to the entire system or not at all. APM recognizes 
five distinct classes of components: system, display, secondary 
storage (e.g., disk), parallel ports, and serial ports. 

APM state transitions occur automatically through system 
actions and manually from applications. The automatic transi¬ 
tions usually result from idle timeouts or declining battery 
strength (see Figure 2 for a diagram that makes automatic 
system-level state transitions more easily understandable). Ap¬ 
plications can manually initiate state transitions through APM 
calls. For example, a communications program could shut off 
the serial port after it had finished using the modem. This 
would conserve power in a fairly transparent way. 
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The Ready state describes a system or component at full 
power and immediately available for use. This state may be 
entered as a result of applying power or may be resumed 
after a Suspended state ends. "Ready" does not distinguish 
between "busy" or "idle” conditions; thus a regular desktop PC 
could be considered to have all its components in the Ready 
state at all times. 

The Stand-by state provides an intermediate level of power 
conservation somewhere between the Ready and Suspended 
states. The system Stand-by state may be entered automat¬ 
ically when the CPU and all components have been idle for a 
predefined timeout period. The system stays in this mode 
until either a device signals a hardware interrupt (IRQ) or a 
controlled device is accessed. All memory contents and opera¬ 
tional parameters are preserved for the duration of the Stand¬ 
by mode. 

The Off state signifies that the system or component af¬ 
fected is powered down and inactive. Although individual 
components may be shut off through APM calls, only a human 
operator can directly switch off the whole system. Memory 
and operational parameters are not guaranteed to be 
preserved when a system or component enters the Off state. 
For example, a shut-off serial port might need to have baud 
rate, parity, and word length reprogrammed before it can be 
used again. 

The Suspended state is the lowest level of power con¬ 
sumption that still preserves memory and operational 
parameters. Unlike other states, the Suspended state must be 
applied at a system level and cannot be applied selectively to 
components. The APM specification notes that the system 
may be immediately sent into the Suspended state when the 
battery becomes "critically low.” Since no CPU activity is al¬ 
lowed in the Suspended state, operation can only be resumed 
by intervention from an external event. The exact method of 
resuming is hardware-dependent and could be as simple as 
having the user hit a special button. 

APM Functions 

The APM function set enables applications to control the 
CPU, set the power state, inquire about pending PM events, 
enable/disable power management, and return power status 
(see Figure 3). Before issuing any of these calls, however, your 
application should check for the presence of the APM inter¬ 
face. The APM Installation Check (ft X=5300h, BX=0000h) returns 
the version number in AX, the capability bits in CX, and a 
check value of "PM” in the BX register. If APM is not present, 
then I NT 15h will set AH=86h. All of the APM functions set the 
CY bit in flags to indicate an error condition. 

Once you've confirmed the presence of APM, you must still 
call APM Interface Connect before you can call most other 
functions. This establishes your link with APM and remains ac¬ 
tive until explicitly removed with APM Interface Disconnect 
(, AX=5304h , BX=0000h). As mentioned earlier, the primary inter¬ 
face to APM for DOS applications is I NT 15h. APM also recog¬ 
nizes that many DOS-extender programs run in protected 
mode rather than real mode or virtual 8086 mode. 

Since dropping down into real mode is an inconvenience 
for protected-mode programs, APM provides separate 16-bit 
and 32-bit interface calling conventions as well. The 16-bit In¬ 
terface Connect ( AX=5302 , BX=0000h ) returns selectors in 
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[AX:BX] pointing to a 16-bit entry point. The 32-bit Interface 
Connect (fiX=5303 ) returns selectors in [AX:BX] pointing to a 
32-bit entry point. These entry points are simply used in lieu 
of the INT 15h call for all subsequent functions. 
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CPU Control 

Once you have connected it to the APM driver, your ap¬ 
plication can call any other APM function, including the CPU 
control functions. The CPU Idle (AX=5305h) and CPU Busy 
( AX=5306h ) functions are the most direct method of controlling 
the CPU. Unlike the power state functions, the CPU control 
functions do not solicit the approval of other APM-aware func¬ 
tions before acting. Thus, the CPU Idle/Busy model is pre-emp¬ 
tive rather than cooperative. 

The CPU idle function tells APM to suspend processing until 
the next system event (i.e., hardware interrupt) because the 
system is inactive. The actual power-saving method is im¬ 
plementation-dependent. For example, the APM might issue a 
HLT instruction, step down to a slower clock rate, or stop the 
CPU clock entirely. The actual method is mostly hidden from 
your application, but you can determine if it merely "slows" 
the CPU by testing bit 2 of the PM capabilities flags (see the 
earlier discussion of the APM Installation Check). 

Since an interrupt terminates the CPU Idle function, it is 
important that Interrupt Service Routines (ISRs) return control 
to the system (IRET) as soon as possible. The APM specification 
warns against writing an application that registers the 
system's return from Idle state and attempts to hand off con¬ 
trol to the application directly from the ISR. In a CPU-slowing 
implementation, this tactic might prevent APM from restoring 
the normal clock rate, because the clock rate change happens 
after the ISR returns. 

The CPU Busy function tells APM to bring the system up to 
normal speed. This function is useful only in situations where 
CPU Idle causes a clock-speed slowdown. Since a hardware 
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interrupt is required to wake the system from a prior CPU Idle 
call, it follows that the ISR invoked by this interrupt may still 
be running at slow speed. If the ISR requires lengthy process¬ 
ing, it can call CPU Busy to bring the system up to normal 
speed for the duration. 

Power States and Events 

The Set Power State function ( AX=5307h ) can affect the en¬ 
tire system, an individual device, or every device of a given 
class. The Power Device ID must be specified in the BX register 
(see Figure 4). For example, an ID of 0401h corresponds to the 
COM2 serial port while an ID of 04FFh corresponds to all serial 
ports (COM 1 ...COMn). Last, the new System State ID must be 
placed in the CX register (see Figure 5). These are the same 
power states as described earlier. 

An application can place the entire system in a Stand-by or 
Suspended state on its own authority if it perceives the sys¬ 
tem to be already idle. However, if other APM-aware applica¬ 
tions are connected, they must be polled before the actual 
state change can occur. Thus an application which has formal¬ 
ly connected to APM is expected to actively watch for power 
event notifications. 

Applications poll for notification of upcoming events by 
calling Get PM Event ( AX=530B). This function returns one of 
five possible enumerated event codes (see Figure 6). The Sys¬ 
tem Stand-by Request and System Suspend Requests imply 
that another APM-aware application has asked for your 
cooperation before the next state transition. In these cases, 
your application must eventually call Set Power State to signal 
its compliance with the pending event. Your application can 
prevent such an event transition simply by ignoring the re¬ 
quest. 

The Normal Resume System and Critical Resume notifica¬ 
tions both occur after the system has completed a 
suspend/resume cycle. In both cases, these notifications mean 
that APM took control of the system without your active 
cooperation. APM may suspend the system any time an emer¬ 
gency situation arises. Applications are expected to recover 
from this as best they can. 

Last, the Battery Low notification tells your application that 
APM may take preemptive action if the current power situa¬ 
tion worsens. Although the APM specification does not provide 
specific advice for low-power conditions, protecting important 


Figure 7 


BH Register 

A.C. Line Status 

BL Register 

Battery Status 

OOh 

Off-line 

OOh 

High 

Olh 

On-line 

Olh 

Low 

FFh 

Unknown 

02h 

Critical 


03h 

Charging 

FFh 

Unknown 


CX = 0 - 100% of battery life remaining or 

255 unknown battery life 

APM Get Power Status Return Values 


Page 22 - Windows/DOS Developer’s Journal 


July 1992 








































data should be your top priority. If your application has any 
sort of “auto-save” backup feature, it should be invoked at 
this time. All data files open for writing should be closed as 
soon as possible. In addition, you might want to warn the 
user of low battery levels before undertaking a lengthy 
process, such as re-indexing a database. 

Control and Status Functions 

Your application can deactivate the entire suite of auto¬ 
matic APM functions with the Disable Power Management call 
( AX=5308h , BX=FFFFh, CX=0000h ). Disabling APM prevents it 
from automatically powering down devices, causes the CPU 
idle call to be ignored, and also prevents the system from 
entering the Stand-by and Suspended states. The Enable 
Power Management function (AX=5308h , BX=FFFFh, CX=0001h) 
returns APM to its previous operating 
conditions. Alternately, Restore Power- 
On Defaults (AX=5309, BX=FFFFh) will 
reset all APM automatic functions to 
their initial factory settings. 

The Get Power Status function 
( AX=530Ah , BX-OOOlh) returns a report 
card on the overall health of the sys¬ 
tem (see Figure 7). The AC Line Status in 
BH tells whether the system is plugged 
into a wall outlet. The Battery Status in 
BL register has several enumerated 
values corresponding roughly to battery 
strength. The most precise reading of 
power remaining is a value from 0 to 
100 in CX. Note that some implementa¬ 
tions may return UNKNOWN (FFh) for any 
or all of these status parameters. 

The Get Power Status and Restore 
Power-On Defaults functions are the 
only two functions an application can 
use without having first been con¬ 
nected to APM. 

Conclusion 

Today’s portable battery-powered 
computers are just as powerful as their 
desktop counterparts. Every DOS and 
Windows application will eventually be 
installed on a portable laptop or 
notebook computer. If you write your 
programs with power conservation in 
mind, your products will be more effec¬ 
tive in this environment than ever 
before. The Advanced Power Manage¬ 
ment specification provides all the 
hooks your software needs to become 
power-friendly quickly and easily. □ 
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ntroduction 

Today, an application program that doesn't provide some 
ort of online help is probably doomed to extinction. For 
tost users, context-sensitive help - that is, help specific to 
ie user's immediate activity - is the key to effective use of 
ie application at hand. 

Context-sensitive help requires the help screens vary 
epending on where the user is in the program. To ac- 
omplish this, some help facilities hard-code the help text 
into the program. This generates very fast help, 
but it uses valuable RAM for text that may not be 
used very often and also causes the program to 
take longer to load. In addition, the amount of 
free RAM limits the size of the hard-coded help 
you can provide. Last, hard-coded help screens re¬ 
quire you to recompile and relink the program 
whenever you revise the help text. In general, 
hard-coded help is useful only in small applications. 

The more commonly used strategy employs a read-only 
database. The application program maintains an index to a 
record in the database, and adjusts the index depending on 
where the user is in the program. When the user presses the 
help key, the help facility uses that index to retrieve and 
display the help screen. This article briefly describes three 
conventional techniques for retrieving the record from the 
database, then presents a fourth technique, which combines 
the best features of the previous three. For each of the data 
file structures, the data file is assumed to be contiguous and 
not fragmented on the disk. 
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Sequential Access Files 

Retrieving help text from a sequen¬ 
tial access file is fairly straightforward. 
You first set the index equal to the 
record you want to retrieve, then ex¬ 
ecute as follows: 

index = 50 

OPEN "help.txt" FOR INPUT AS 1 
FOR i = 1 TO index 

INPUT#1, Text$ 

NEXT i 
CLOSE 1 

The advantage of sequential access 
files is that you can use variable length 
records. Also, in some cases, such as a 
text file, you can update the data file 
using a text editor or word processor. 
This makes sequential access record 
files easy to develop and update. 

The disadvantage of sequential ac¬ 
cess files lies in the time required to 
retrieve the higher numbered records. 
As the record number to be retrieved 
increases, the delay time also increases, 
in a linear fashion. This means that it 
takes 5 times as long to access the 
50th record as it does to access the 
10th record, and 50 times as long as to 
access the first record. Thus if your pro¬ 
gram takes half a second to retrieve 
the first help record, your user will wait 
over 25 seconds for the 50th record. For 
this reason, sequential access files 
make a poor choice for accessing help 
records. 

Random Access Files 

Random access files overcome the 
delay time associated with sequential ac¬ 
cess files. The amount of time required to 
retrieve the desired record is the sum 
of the relative byte calculation time 
(the time to calculate where the data is 


Listing 1 (help.bas) 


•************************************************************** 
i***** ***** 

'*** Fast Indexed Help November 1991 *** 
'* Program: HELP.BAS * 
• * * 

'* Copyright (C) 1990, 1991 George R. Toft * 
'* 92-902 Welo St, #94 * 
'* Makakilo, HI 96707 * 
'* Original creation date: March 1990 * 
'* Reduced to minimum size: November 1991 * 


I *** 

I ***** 


*** 

***** 


************************************************************** 


'=======*==*=== Type Declaration Section ============== 

DEFINT A-Z 


'============== Procedure Declaration Section ========= 

DECLARE SUB Display (MasterHelpTextS, RecordNum AS INTEGER) 
DECLARE SUB GetEnter () 

DECLARE SUB GetMasterHelpText (Record AS INTEGER, MasterHelpText 
AS STRING) 

DECLARE SUB HelpMain (MasterHelpText$, Index AS INTEGER) 

DECLARE SUB IINC (Argument AS INTEGER) 

'=====:::====== Execution Section ===================== 

1 This is the minimum program to retrieve help records. 

' There is minimal processing performed on the data, it is 
1 simply retrieved and displayed. 

FOR RecordToGet = 10 TO 1 STEP -1 

HelpMain MasterHelpText$, RecordToGet 
Display MasterHelpTextJ, RecordToGet 
NEXT RecordToGet 
CLS 
END 

SUB Display (MasterHelpTextJ, RecordNum AS INTEGER) 

CLS 

PRINT "Help record number"; RecordNum 
PRINT “ 

PRINT MasterHelpText$ 

GetEnter 
END SUB' Display 

SUB GetEnter 
PRINT 

PRINT TAB(34); “Press [Enter]”; 

DO WHILE INKEY$ <> CHR$(13): LOOP 
END SUB' GetEnter 

DEFSNG H 

SUB GetMasterHelpText (Record AS INTEGER, MasterHelpText AS 
STRING) 

‘ This routine looks up the location of MasterHel pText in 
1 HELP.IDX, then retrieves it from HELP.TXT. 
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Listing 1 — Cont’d 


1 use index to look up help location 
OPEN “HELP.IDX" FOR RANDOM AS 1 LEN = 5 
FIELD #1, 5 AS CountFieldS 
GET #1, Record 
HelpStart = CVS(CountFieldS) 

GET #1, Record + 1 

HelpEnd = CVS(CountFieldS) - 2' Remove CR+LF at end 
CLOSE 1 

' Retrieve the MasterHelpText 
SELECT CASE HelpStart 
CASE IS = 1 

OPEN "HELP.TXT” FOR RANDOM AS 1 LEN = HelpEnd 
FIELD #1, (HelpEnd - HelpStart) AS FieldLineJ 
GET #1, 1 

MasterHelpText ■ FieldLineS 
CLOSE 1 

CASE IS <= 1000 

OPEN “HELP.TXT" FOR RANDOM AS 1 LEN = HelpEnd 
FIELD #1, HelpStart AS TrashS, (HelpEnd - HelpStart) AS 
FieldLineS 

GET #1, 1 

MasterHelpText = FieldLineS 
CLOSE 1 
CASE ELSE 

RecordToGet = HelpStart \ 1000 + 1 

HelpStart = HelpStart - (RecordToGet - 1) * 1000! 

HelpEnd = HelpEnd - (RecordToGet - 1) * 1000! 

IF HelpEnd > 1000 THEN ' Text crosses record boundary 
OPEN "HELP.TXT" FOR RANDOM AS 1 LEN = 1000 
1 get first piece of MasterHelpText 
FIELD #1. HelpStart AS TrashS, (1000! - HelpStart) 

AS FieldLineS 

GET #1, RecordToGet 
MasterHelpText = FieldLineS 
1 get middle pieces 
FIELD #1, 1000 AS FieldLineS 
FOR i = 1 TO HelpEnd \ 1000 - 1 
IINC RecordToGet 
GET #1, RecordToGet 

MasterHelpText * MasterHelpText + FieldLineS 
NEXT i 

1 get last piece 

FIELD #1, (HelpEnd MOD 1000) AS FieldLineS 
GET #1, RecordToGet + 1 
MasterHelpText = MasterHelpText + FieldLineS 
CLOSE 1 

ELSE 

OPEN "HELP.TXT" FOR RANDOM AS 1 LEN = 1000 
FIELD #1, HelpStart AS TrashS, (HelpEnd - HelpStart) 
AS FieldLineS 

GET #1, RecordToGet 
MasterHelpText * FieldLineS 
CLOSE 1 
END IF 
END SELECT 

END SUB' GetMasterHelpText 
DEFINT H 

SUB HelpMain (MasterHelpTextS, Index AS INTEGER) 

1 load in help pages 

1 A sequential file is used to allow for a variable 
' length record. The record is terminated with a <CR>. 

GetMasterHelpText Index, MasterHelpTextS 

' clear up free string space 
Temp! = F R E("") 

END SUB' HelpMain 

SUB I INC (Argument AS INTEGER) 

Argument « Argument + 1 
END SUB' I INC 


stored relative to the beginning of the 
data file), the disk’s seek time (the time 
to move the heads to that location), the 
disk's latency time (the time to wait 
before the data appears under the 
read/write heads), and the transmission 
time (the time to get the data to the 
computer). Even though the seek time 
varies randomly depending on the loca¬ 
tion of the next record to be retrieved 
and latency time can vary up to 1/60 
second for 3600-RPM hard drives (1/6 
second for floppy drives), the relative 
byte calculation time and the transmis¬ 
sion time are constant. Since the 
average of this sum can be shown to 
approach some average value, random 
access files yield a constant record 
retrieval time independent of the record 
number to be retrieved. The following 
uses random access files to perform the 
same function as the sequential access 
file procedure listed earlier: 

index = 50 

OPEN "help.txt" FOR RANDOM AS 1, 

LEN = 6000 

FIELD 1, 6000 AS TextBufferS 
GET#1, 50 
CLOSE 1 

The disadvantage here is that since the 
operating system must know the size 
of each record in order to perform its 
retrieval calculation, records must be 
the same length. This requirement 
results in a significant waste of disk 
space and, in many cases, would 
preclude the program’s being run from 
a floppy disk. 

Traditional Indexed 
Sequential Access Files 

Traditional indexed sequential access 
files differ from the sequential access 
files discussed earlier only in that they 
use an index to locate the record on 
the disk drive. IBM developed this tech¬ 
nique as their “Indexed-Sequential Ac¬ 
cess Method” (ISAM). IBM ISAM index 
files provide the cylinder and track in¬ 
formation for the data file, and are 
therefore very device dependent. Since 
the database itself contains the location 
of the desired record, there’s no need 
for computation - a call to the operat¬ 
ing system will retrieve the desired 
record for you. You can update the data 
file as you would any other sequential 
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Listing 2 (help.txt) 


1. The first record exercises the case where the desired data is 
at the beginning of the HELP.TXT. 

2. The second record exercises the case where the desired data is 
after the beginning of the file, but prior to the 1000th byte in 
the file. 

3. The third record is just like the second record. This record 
is used to occupy space so that record 9 crosses the 1000 byte 
boundary. 

4. The fourth record is just like the third record. This record 
is used to occupy space so that record 9 crosses the 1000 byte 
boundary. 

5. The fifth record is just like the fourth record. This record 
is used to occupy space so that record 9 crosses the 1000 byte 
boundary. 

6. The sixth record is just like the fifth record. 

7. The seventh record is just like the sixth record. 

8. To exercise all of those sections requires this help file be 
longer than 1000 bytes, and that at least one record cross the 
1000 byte boundary. 

9. HELP.BAS, the no-frills demonstration, is written so that the 
highest records are read first. This demonstration exercises all 
of the sections of code in the GetMasterHelpText routine. This 
record, in particular, crosses the 1000 byte boundary. It begins 
at the 912th byte and goes to the 1221st byte. 

10. This is record number 10 of the HELP.TXT file. Remember, 
HELP.BAS reads the records in decending order. This record 
exercises the case in the procedure GetMasterHelpText where the 
record resides beyond the 1000 byte boundary. 


Sample Help File 


Listing 3 (index.bas) 

1 Fast Indexed Help indexer 

' This program creates an index to the input .TXT file 
1 Written: April 2nd, 1990 
1 Modified: November 1991 
' Language used: QuickBASIC 4.5 
1 Author: George Toft 

jyp e Definition Section =============== 

DEFSNG A-Z 
DEFINT D 

Constant Definition Section =========== 

CONST FALSE = 0, TRUE = NOT FALSE 

'=========,===== Subroutine Definition Section ========= 

DECLARE SUB DRAWWINDOW (Top AS INTEGER, Left AS INTEGER, Bottom 
AS INTEGER, Right AS INTEGER, Border AS INTEGER, LineStyle AS 
INTEGER, Bkgnd AS INTEGER) 

DECLARE SUB INC (Arg AS SINGLE) 

DECLARE SUB PRINTSTRING (Y AS INTEGER, X AS INTEGER, text AS 
STRING) 

DECLARE SUB SetAttrib (Top AS INTEGER, Left AS INTEGER, Bottom AS 
INTEGER, Right AS INTEGER, Attrib AS INTEGER) 

'»*=*****=**=* Execution Section ===================== 

ErrorlnFile = FALSE 

Get name of file to index --- 
CLS 

FileToIndex$ = LEFTS(C0MMAND$, INSTR(COMMAND$ + “ \ " “)) 
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access file with constant record lengths, 
which means using an input and an 
output file to receive the updated text. 
The disadvantage to using ISAM files is 
that the help file would have to be re¬ 
indexed every time the program started 
to make sure that its physical location 
hadn’t changed since the last time the 
application was run. 

Modified Indexed 
Sequential Access Files 

The modified indexed sequential ac¬ 
cess (MISA) files discussed here employ 
the best of all three file access 
strategies. You can update the help text 
quickly and easily using nothing more 
than a text editor or word processor. 
The data records can be variable length, 
which keeps the help file as small as 
possible, saves precious disk space, and 
enables floppy disk use of your pro¬ 
gram even with an extensive help 
facility. The MISA routine accesses 
record quickly, retrieving the last record 
in a file in just slightly more time than 
the first record, so that MISA file perfor¬ 
mance approaches that of the random 
access file strategy. The MISA technique 
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Listing 3 — Cont’d 

1 — Verify file exists — 

ON ERROR GOTO FileError 

OPEN FileToIndex$ + ".TXT" FOR INPUT AS 1 

CLOSE 1 

ON ERROR GOTO 0 

1 — If file exists, then run program; else quit 
IF (NOT ErrorlnFile) THEN 

1 — Create viewing windows — 

CLS 

DRAWWINDOW 9, 4, 11, 10, &H7, DOUBLELINE, &H7 
DRAWWIND0W 9, 19, 11, 27, &H7, DOUBLELINE, &H7 
DRAWWINDOW 14, 4, 16, 76, &H7, DOUBLELINE, &H7 
«— open text file for input — 

OPEN FileToIndexS + ".TXT" FOR INPUT AS 1 
1 — create the index file — 

OPEN FileToIndexS + \IDX“ FOR RANDOM AS 2 LEN = 5 
FIELD #2, 5 AS CountFieldS 

1 The first record in the index will always 
1 point to the first byte in the text file, 

1 so make record #1 equal to 1 and start 
1 processing with record 2 
LSET CountField$ = MKS$(1) 

PUT #2, 1 
record = 2 
Count » 0 

1 Process text until the end of the text file 
1 is reached. 

DO WHILE NOT E0F(1) 

LINE INPUT #1, line$ 

1 Count keeps a running total of bytes read 
1 from the text file. By saving Count 
' after reading each line in the text file, 

’ Count point to the beginning of the next 
1 line in the text file, and an index to 
' the text file is created. Add two to 
1 Count to account for CR+LF at the end 
1 of the input line. 

Count = Count + LEN(line$) + 2 
1 This record points to the beginning of 
1 the next line of text (or the end of this 
1 line of text - 1). 

LSET CountFieldS = MKSS(Count) 

PUT #2, record 

1 Display the current record number, the 
1 index, abd the first 60 characters of 
' the input line. 

PRINTSTRING 10, 5, STRS(record) 

PRINTSTRING 10, 20, STR$(Count) 

PRINTSTRING 15, 5, SPACE$(60) 

PRINTSTRING 15, 5, LEFTS(1ine$, 60) 

' Advance to the next record and 
1 continue processing. 

INC record 

LOOP 
CLOSE 2 
CLOSE 1 
CLS 

PRINT "Indexing complete:" 

PRINT "Total number of records ; record 

PRINT "Total number of bytes in help file ="; Count - 1 

PRINT 

ELSE 

PRINT "Error in filename to be indexed ("; FileToIndexS; 
“.TXT)." 

PRINT "Ensure you enter the filename without the " 

PRINT "extension when you invoke INDEX. For example:" 
PRINT "type 'INDEX HELP' to index HELP.TXT and create" 
PRINT "the index HELP.IDX" 

PRINT "Index terminated in error." 

END IF 
END 
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Listing 3 — Cont’d 


'=============. Error Trap section ==================*= 

FileError: 

ErrorlnFile « TRUE 
RESUME NEXT 
DEFINT A-C, E-Z 
'$Page 

SUB DRAWWINDOW (Top AS INTEGER, Left AS INTEGER, Bottom AS 
INTEGER, Right AS INTEGER, Border AS INTEGER, LineStyle AS 
INTEGER, Bkgnd AS INTEGER) 

SetAttrib Top, Left, Bottom, Right, Border 
SELECT CASE LineStyle 
CASE SingleLine 

PRINTSTRING Top, Left, "" + STRING$(Right - Left - 1, “") + 

FOR i ■ Top + 1 TO Bottom - 1 

PRINTSTRING i. Left, "" + SPACE$(Right - Left - 1) + "" 

NEXT i 

PRINTSTRING Bottom, Left, "" + STRINGS(Right - Left - 1, "") + "" 
CASE DOUBLELINE 

PRINTSTRING Top, Left, "" + STRINGS(Right - Left - 1, ““) + *" 

FOR i = Top + 1 TO Bottom - 1 

PRINTSTRING i. Left, + SPACE$(Right - Left - 1) + 

NEXT i 

PRINTSTRING Bottom, Left, + STRINGS(Right - Left - 1, "") + 
END SELECT 

SetAttrib Top + 1, Left + 1, Bottom - 1, Right - 1, Bkgnd 
END SUB' DrawWindow 

DEFSNG A-Z 
'$Page 

I 

SUB INC (Arg AS SINGLE) 

Arg * Arg + 1 
END SUB' I INC 

DEFINT A-Z 
'$Page 

I 

I 

SUB PRINTCENTER (text AS STRING) 

1 prints text in center of screen at current row 
PRINTSTRING CSRLIN, 41 + POS(O) - LEN(text) \ 2, text 
PRINT 

END SUB' PRINTCENTER 
'$Page 

I 

SUB PRINTSTRING (Y AS INTEGER, X AS INTEGER, text AS STRING) 

DEF SEG = &HB800 

FOR i = 0 TO LEN(text) - 1 

POKE (Y * 80 + X + i - 1) * 2, ASC(MID$(text, i + 1, 1)) 

NEXT i 

END SUB 1 Printstring 
'$Page 

I 

SUB SetAttrib (Top AS INTEGER, Left AS INTEGER, Bottom AS 
INTEGER, Right AS INTEGER, Attrib AS INTEGER) 

DEF SEG = &HB800 
FOR i - Top TO Bottom 
FOR j = Left TO Right 

POKE (i * 80 + j - 1) * 2 + 1, Attrib 
NEXT j 
NEXT i 

END SUB' SetAttrib 



Graphics Interface (TGI) 

CGA, Hercules, EGA, VGA, VGAX mode 
and Super VGA. 256 colors. 800 x 600 & 
1024x 768. Fast scrolling. Autodetection. 
Supports cards by Ahead, Ati, C&T, 
Everex, Trident, Tseng, Video 7and more. 
BGI function compatible. Fast bit image 
fonts, 40 included. Full source code in¬ 
cluded. $ 99 

Virtual Memory Manager (VMM) 
UsesXMS, EMS and hard drive. Source 
code included. $ 99 

Font editor & Icon editor 

Includes 200 fonts and application 
source. $ 99 



Graphical User Interface (GUI) 

Fast, flexible and easy to use. Includes 
menus, mouse support, buttons, file 
selector, dialogues, pick lists world co¬ 
ordinates and much, much more. Struc¬ 
tured and OOP interface provided. In¬ 
cludes source for GUI and runtime for 
TGI & VMM $ 99 



TEGL Systems Corporation 
780-789 West Pender Street 
Vancouver, B.C. Canada V6C 1H2 
Phone (604) 669-2577, Fax (604) 688-9530. 
Shipping & Handling $15 
($30 outside Canada & US) 

Visa & Mastercard accepted. 

Works with Borland, Intel, Metaware, Microsoft, 
WATCOM, Topspeed, Turbo & Zortech C. 
Turbo Pascal & Stony Brook Pascal-!-. Does 
not require or work with Microsoft Windows. 

Trademarks are property of their respective holders. 


July 1992 


□ Request 346 on Reader Service Card □ 
Windows/DOS Developer's Journal — Page 29 

















































uses an index (like ISAM files) and random access record 
retrieval. In a test of retrieval time for the uppermost records 
of a 150-topic help database, traditional sequential access files 
took almost 45 seconds, while MISA files retrieved, formatted, 
and displayed the last record in under two seconds. 

The MISA Concept 

The MISA file structure achieves vastly improved perfor¬ 
mance by treating the sequential access file as a random ac¬ 
cess file with one record. Generally, that record has two vari¬ 
able length fields, determined by the values in the index file. 
To access the desired record (as determined by index), the 
routine opens the index data file, then reads the index record 
to find out where the desired data begins and the index+1 
record to determine where the data ends. It then opens the 
help file, ignores the characters up to the beginning of the 
data, and reads the desired data - theoretically, in one disk 
read. Two exceptions must be handled: first, where the record 
being retrieved is the first record, in which case there is only 
one field - the one that contains the help data; and second, 
where the record to be retrieved requires the first field to be 
larger than 1000 bytes. In the second case, the data file is 
divided into 1000-byte fields and the file pointer is advanced 
to the desired record by directly accessing the record prior to 
the desired record. In this case, the desired record is still ob¬ 
tained in one (or two) disk reads. The 1000-byte limit is ar¬ 
bitrary - it was chosen to minimize the amount of RAM used 
by the file's I/O buffer. 

The following example illustrates how the MISA file struc¬ 
ture works: Suppose you want the 50th help record. The help 
facility opens the help index file for random access and reads 
the 50th and 51st records (index and index+1). Assume these 


Listing 4 (example.bas) 

IntroScreen 

Choice = 1 
DO 

Menu$(0) * "Main Menu Title" 1 Main menu title 
Menu$(l) ■ “First Choice" 

Menu$(2) = "Second Choice" 

Menu$(3) = "Third Choice" 

Menu$(4) = "Quit Program" 

Menu$(5) ■ "" ' Null indicates end of menu items 
Helplndex = 0 

PrintMenu Choice, Helplndex 

SELECT CASE Choice 


END SELECT 

LOOP UNTIL Choice = 4 

CLS 

END 

Example Context-sensitive Help Program 


values are 8123 and 8991, respectively. The help procedure 
must now access the text file beginning at byte 8123, going to 
byte 8991. To do this it divides the file into 1000-byte pieces 
and retrieves the eighth record (8123 divided by 1000). It then 
fields the record into two pieces, 123 bytes of trash (8123 
modulus 1000) and 868 bytes of help data (8991 minus 8123). 
The last nine bytes are ignored. 

This works well if all of the data records fall neatly inside 
the 1000-byte boundaries, but this is often not the case. 
Making the boundary larger would minimize the occurrence, 
but the event would still happen. Given that string variables 
(hence field identifiers) in QuickBASIC cannot be larger than 
64Kb you could avoid the boundary crossing altogether by 
limiting your help file to less than 64Kb. However, there is a 
better way to deal with this situation. 

if the desired help data crosses the 1000-byte boundary, 
the help facility reads the help index file as before. Assuming 
the 50th record begins at byte 8900 and ends at byte 9234, 
the two bytes read from the index file equal 8900 and 9234. 
When the help facility notices that the desired data crosses 
the 1000-byte boundary, it makes two reads from the help 
file. On the first read, it ignores the first field (8899 bytes), but 
saves the last field (101 bytes). On the second, it reads the 
next 1000-byte record and appends the first field (233 bytes) 
onto the last field of the previous record (for a 334-byte help 
record). 

The MISA Program 

Listing 1, help.bas, contains the fast indexed help routines. 
The main program accesses the records in reverse order, 
beginning with record 10 and ending with record 1. While this 
is only a demonstration, all of the subroutines are complete. 
The description for the help routines follows the discussion of 
the help file indexing program. 

The help file, help, txt, used by help.bas is shown in List¬ 
ing 2. The records in the listing are broken onto multiple lines 
to fit on the magazine page, but in the actual file, each record 
should be on a single line. 

To get help.bas to run, you need to create the index file 
with the indexing program in index.bas, Listing 3. To use it, 
compile it as a standalone module and run it from the com¬ 
mand line, specifying the name of the file to index. The help 
file must have the . txt extension, which is omitted on the 
command line. For example, to index the file help.txt you 
must type index help and press Enter. The indexing program 
assumes the file help.txt is to be indexed, and creates the 
index file help, idx in the default directory. Since the program 
is simple and thoroughly commented, ! will not describe it in 
detail here. Briefly, the program reads a line from the specified 
help file, counts its length and adds two (for the carriage 
return and line-feed characters), adds that value to the total 
byte count, and outputs the total to the index file. The 
program's preliminaries verify the help file's existence and 
open up the help and index files for access. 

help.bas contains the following subprograms, which per¬ 
form the functions indicated: 

• Display () - Displays the current record number and a por¬ 
tion of the help record on the screen. 

• GetEnterf) - Loops until the Enter key is pressed. 
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• GetMasterHelpText() - The workhorse routine: looks up 
the location of the variable MasterHelpText in help.idx 
based on the specified record, then retrieves it from 
help.txt. Incorporates all of the requirements discussed 
above for retrieving help text under various circumstances. 

• HelpMain() - Calls GetMasterHelpText and clears up the 
string space. In a more extravagant system, this routine 
would save the screen, format and display the help text, 
then restore the screen after the user is finished reading 
the help text. 

• IINC() - Increments the integer argument sent to it. 

All of these routines are simple and self-explanatory except 
for GetMasterHelpText (), which requires some discussion. 

GetMasterHelpText() (see Listing 1) has two parameters: 
Record and MasterHelpText. Record is an input parameter, 
and MasterHelpText is the returned value. A function might 
work in this case, but QuickBASIC has a tendency to waste 
string space, so assigning a large string to a function would 
waste space more quickly, expediting the need for garbage 
collection. 

Retrieving the help text from the help file is a two-part 
process: identifying where the help text is located and retriev¬ 
ing it. GetMasterHelpText() determines the location of the 
help text by opening the index file help, idx and reading the 
records pointed to by Record and ( Record + 1) as HelpStart 
and HelpEnd, respectively. These two values point to the 
beginning and end of the help text located in the help file, 
help. txt. 

To retrieve the help text, GetMasterHelpText() must 
determine which case it is dealing with, since the text could 
be the very first record, could be located within the first 1000 
bytes of the file, or could be located somewhere beyond the 
first 1000-byte boundary. If HelpStart = 1, then the help 
record is at the beginning of the help file, and GetMaster- 
HelpTextO needs only to retrieve the first (HelpEnd - Help- 
Start) bytes of the help file. This is accomplished in the first 
SELECT CASE condition, where the help file is opened and the 
FIELD statement defines (HelpEnd - HelpStart) bytes as 
FieldLine$, which is assigned to the variable MasterHelpText 
after the first record is retrieved. 

If the help text lies within the first 1000 bytes, but after 
the first byte, the second SELECT CASE condition takes effect. 
Here the help file is opened, and the FIELD statement defines 
HelpStart bytes as Trash$ and (HelpEnd - HelpStart) 
bytes as FieldLine$, which is assigned to the variable 
MasterHelpText after the first record is retrieved. Trash$, as 
its name implies, is ignored. 

If the first two CASES are not executed, CASE ELSE takes 
effect, which means the help text is located somewhere 
beyond the first 1000-byte boundary. In this case, the routine 
assigns the value of the 1000-byte record to be retrieved to 
the variable RecordToGet. Then it adjusts HelpStart and 
HelpEnd to point within the RecordToGet record. 

Next, GetMasterHelpText() checks to see if the help text 
crosses a 1000-byte boundary. If it does, GetMasterHelp¬ 
Text () retrieves the first piece of help text, which begins at 
HelpStart in the RecordToGet record, going up to either the 
1000th byte or HelpEnd. GetMasterHelpText () then uses a 
FOR loop to access each subsequent record until it reaches the 
record where HelpEnd points. Finally, it retrieves the last piece 


of help text, beginning at the 1000th byte and going up to 
HelpEnd. This code takes advantage of several BASIC variable 
initialization features that are not found in other languages. In 
this case, all strings are initialized to null, so it is not neces¬ 
sary to check for a middle piece of help text.. The code as¬ 
sumes that a middle and end piece exist - if the assumption 
is incorrect, nulls are appended to the variable MasterHelp¬ 
Text, which has no effect on the value. 

If HelpEnd is within the 1000-byte boundary of the 
RecordToGet record, GetMasterHelpText() retrieves the help 
text much as it does in the second case. Here, however, it 
retrieves the RecordToGet record and the FIELD statement 
defines HelpStart bytes as Trash$ and (HelpEnd - Help- 
Start) bytes as FieldLineS, which is assigned to the variable 
MasterHelpText after the first record is retrieved. Trash$ is 
still ignored. 

The Integrated Menu-Help Program 

Listing 4 (example.bas) contains a code fragment that 
demonstrates how to put this help system to work. Intro- 
Screen is your introductory routine. Menu$() is a global array 
of strings used to hold the menu choices. PrintMenu is a 
routine you must supply that uses the cursor keys or mouse 
to select one of the menu items. The choice is returned in the 
integer variable Choice. The easiest way to get the correct 
help text is to add the currently selected choice, Choice, to 
the help index, Helplndex. Helplndex acts like a base pointer 
to the correct block of help text messages, and Choice acts 
like an offset pointer to the correct help text. Using this 
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strategy, PrintMenu must respond to the FI key by calling the 
procedure HelpMain with the sum of Choice and Helplndex 
for the help text message to retrieve. For example, to display 
the appropriate help text, PrintMenu should execute this line 
after detecting the FI key: 

HelpMain Helplndex + Choice 


Your version of the HelpMain routine must take care of the 
required screen saves to display the help text, then restore 
the screen to normal so the menu can continue operation. 

Summary 

Incorporating the fast indexed help system into your pro¬ 
gram greatly improves your help text retrieval time. The 
routines work with traditional menu-based user interfaces as 
well with dropdown menu interfaces. Given the text retrieval 
routines’ execution speed and ease of use, you can significant¬ 
ly improve the performance of your program. □ 
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Programming 
the 16550 UART 

Charles B. Allison 

While the PC CPU has evolved from 4.77MHz 8088 
processors to 80486 processors of almost ten times that 
clock speed, other parts of the PC architecture have not 
been totally asleep; the venerable RS-232 COM port 
hardware has also undergone significant changes. This ar¬ 
ticle shows how to take advantage of the new National 
Semiconductor 16550 UART, a serial interface chip that 
produces more efficient high-speed serial I/O by virtue of 
two internal sixteen-character FIFO (First-In, First-Out) buf¬ 
fers. 

I provide a small, interrupt-driven serial interface 
library for DOS, along with a simple example program. All 
of the code is written in Microsoft C and should, with very 
minor modification, work also with Borland C. The pro¬ 
gram works correctly with the traditional 8250 PC UART, 
but takes advantage of the FIFOs and other new features 
when the National 16550 is present. To understand the 
library's functions, you need to understand the basics of 
interrupt-driven serial I/O (see the references at the end 
of the article). 

Introduction 

The original PC serial interface used the 8250 UART 
chip. The 8250 UART has only a one-byte receive buffer, 
which means that after the 8250 receives a character, you 
have to retrieve it before the next character arrives or 
you will have an overrun error. Most PCs are fast enough 
to handle this at speeds up to 9,600 baud. At 1,200 baud, 
a new character arrives about every eight milliseconds - 
plenty of time for an interrupt handler to fetch the char¬ 
acter from the UART and store it in a receive buffer. But 
at 19,200 baud, a new character arrives about every half 
millisecond, and at 115,200 baud (the maximum speed of 
the standard PC COM port), about every 90 microseconds. 
Depending upon your CPU speed, you may not have 
enough time to reliably service one interrupt per character. 


Charles Allison has been working with microprocessor 
hardware and firmware in embedded systems since 1975. 
He has a BS degree in physics and a Master of Business 
Administration degree. Charles has a microprocessor con¬ 
sulting business, Allison Technical Services, where he has 
been developing embedded control and monitoring 
products for clients since 1984. Charles can be reached 
through his BBS/FAX line at ( 713)-777-4746 or his company, 
ATS, 8343 Carvel, Houston, TX 77036. 
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Some software manages to work at these higher speeds 
by sending and receiving data in burst blocks. Such software 
uses the UART interrupt to detect the first character of an 
incoming block, but then disables the UART interrupt and 
simply polls the 8250 in a very tight loop until the last charac¬ 
ter in the block arrives. 

The 16550 

Kudos to National Semiconductor. Their 16550 UART has in¬ 
creased the usable speed of the PCs COM port by more than 
an order of magnitude. What's more, they did it while main¬ 
taining PC compatibility both in hardware and in software. 

With respect to hardware compatibility, only two of the 
forty pins on the 16550 differ from the 8250 and those should 
be unused for PC-compatible serial ports. Pins 24 and 29 have 
changed from CS0UT and No Connect to RXRDY/ and 
RXRDY/DMA output connections. It is possible to plug the 16550 
into existing 8250 serial cards. If the card manufacturer chose 
to connect something (such as a ground wire) to either of 
these pins, you should be able to simply clip the pin off or 
bend it out so it does not go into the socket. 

As for software compatibility, National has made it easy for 
new software using the FIFO buffers to work with the older 
UARTs. When you first boot the PC, the 16550 will reset to a 
compatibility mode, so 8250 software does not know the dif¬ 
ference. The I/O registers you use to program the 16550 
remain the same as for the 8250 except for a few extensions 
that allow you to take advantage of the new capabilities. 

Programming the 16550 

The 16550 contains a new register, the FIFO Control 
Register (FCR), as shown in Figure 1. You set bits in this write- 
only register to enable or disable the FIFO buffers or reset the 
transmit or receive FIFO buffer. The write-only 16550 FCR 
shares the same I/O port offset as the read-only 8250 Inter¬ 
rupt Identification Register (HR), the third byte from the base 
address of the COM port. 

The 16550 also slightly redefines the existing HR register. 
The HR in the 8250 tells you if an interrupt is pending and 
what type it is. The 8250 HR uses only the lower three bits of 
the register to convey this information. Since the other five 
bits are free, the 16550 uses the top two bits to indicate that 
the FIFO buffers are enabled. For example, you can see if FIFOs 
are enabled like this: 


Idefine FifoOn(base) \ 
((inp(base+2)&0xF0) \ 

== OxCO) 

In fact, I detect the presence of the 
16550 by attempting to turn on the 
FIFO buffers (writing to the FCR will 
have no effect on an 8250) and then 
checking the upper bits of the HR. 
Before you turn on the FIFO buffers, 
however, you have to decide on your 
buffering strategy. 

The 16550 can buffer 16 characters, 
both for transmission and reception. To 
enable these buffers, all you have to 
do is write a 1 to the least significant bit of the FCR. That 
simple change lets your software operate at higher speeds, 
since you would have to fall 16 characters behind, rather than 
1 character behind, before you lost any incoming data. At 
115,200 baud, this means that instead of having to read a 
received character in under 90 microseconds or risk an over¬ 
run error, you now have over 1.2 milliseconds to service the 
UART and read in characters. 

Speed is not the only motivation for using the FIFO buffers, 
however. If your software operates in a multitasking environ¬ 
ment (such as Windows), you may be more interested in 
reducing the number of interrupts so that serial communica¬ 
tions do not slow down the other activities on the machine. 
The 16550 allows you to postpone raising an interrupt until 
more than one character has arrived. You can program the 
FCR to interrupt when the FIFO buffer contains one character, 
four characters, eight characters, or fourteen characters. By 
setting the interrupt for multiple characters, you reduce the 
number of times your interrupt service routine gets called and 
retrieve more characters at each interrupt. Windows 3.0 did 
not support the 16550, but the new Windows 3.1 serial port 
driver does. 

What happens if you've programmed the 16550 to inter¬ 
rupt at eight characters, but only four characters arrive? A 
built-in timer automatically triggers the receive interrupt if any 
characters are in the FIFO and no more characters have been 
received over a period of time equal to about four character 
lengths. This keeps characters from getting stuck undetected 
in the FIFO buffer. 

What if several characters are in the receive FIFO buffer 
and a line error occurs? The 16550 loads both characters and 
line error bits into the FIFO buffer, so you will detea the error 
in the same sequence it occurred. 

An Example Program 

Listing 2 ( uartdvr.c) contains a very simple interrupt- 
driven serial I/O C program that demonstrates how to take 
advantage of the 16550's FIFO buffers. Listing 1 ( serialc.h ) 
contains the corresponding header file. Only a few lines of 
code are specific to the 16550; I just enable and reset the FIFO 
buffers, then verify that they were enabled in case the 
machine has an 8250 instead of a 16550. 

comint () is the communications interrupt funaion. It is a 
far interrupt function with no arguments or return value. 
Processor registers will be automatically saved to the stack on 
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entry and restored on exit. Processor interrupts are automat¬ 
ically disabled on entry and enabled on exit. The routine per¬ 
forms three activities. First, comint () determines the source of 
the interrupt. Second, comint() calls the associated function 
to process the interrupt activity. Third, when all pending inter¬ 
rupt requests from the UART have been performed, comint () 
clears the 8259A interrupt request, isr, an array of four func¬ 
tion pointers, contains the functions used to handle specific 
UART interrupt request sources. 

The last argument of set_mode() deserves a little explana¬ 
tion. The parity character indicates which parity option you 
want and can have the following character values: “S” for 
space, “M" for mark, “E" for even, "0” for odd, “N” for none. 

main() provides a simple demonstration of the serial 
library. It sets up the UART for interrupt-based operation and 
then proceeds to act almost as a dumb terminal program. The 
primary difference between this program and the usual dumb 


terminal is that it sends keyboard characters to the serial port 
a line at a time instead of when you type each character. 
Defining TESTFIFO enables an option that provides you with a 
maximum count of characters received while in the interrupt 
routine. This character count is displayed when you end the 
program by pressing the Escape key. On termination, the pro¬ 
gram restores the original interrupt vector to DOS and restores 
the original interrupt mask bit to the 8259A. It does not re¬ 
store the UART's original register values. 

The example program is of limited use as a dumb terminal 
since it buffers the keyboard characters into a line before 
transmitting. However, it does provide two pieces of very use¬ 
ful information: what kind of UART you have and how fast 
you can safely run your serial port. The presence of a 16550 
instead of the 8250 will be indicated by the FIFO size. By con¬ 
necting TX and RX together (pins 2 and 3 on the serial port 
connector) you can determine the machine's capacity to 


Listing 1 (serialc.h) 


/* Serial Interface 

written by: Charles B. Allison, ATS 
Last Change: 2-28-92 14:00 */ 

J-k *********************************** */ 

/*-hardware defines-*/ 

♦define IRQ_0FF 8 /* offset int vector of irq 0 


8 */ 


♦define PIC01 0x21 /* 
♦define PI COO 0x20 /* 
Idefine EOI 0x20 /* 
Idefine MAX BAUD 1162001 
♦define COMl 0x3f8 /* 
Idefine COM2 0x2f8 /* 
Idefine COM3 0x3e8 /* 
Idefine COM4 0x2e8 /* 


8259 mask register */ 
8259 command register */ 
end of interrupt cmd */ 
/* maximum baud rate */ 
coml:*/ 


com2:*/ 
com3:*/ 
com4:*/ 
irq number 
irq number 
irq number 


Idefine IRQ3 0x3 / 

Idefine IRQ4 0x4 /' 

Idefine IRQ5 0x5 / 

Idefine BASE base 
Idefine TXD BASE 
Idefine RXD BASE 
Idefine DIVLSB BASE 
Idefine DIVMSB (BASE+1) 

Idefine INTEN (BASE+1) 

Idefine INTID (BASE+2) 

Idefine FIF0C (BASE+2) 

Idefine LINECTL (BASE+3) 

Idefine MODEMCTL (BASE+4) 

Idefine LINESTAT (BASE+5) 

Idefine M0DMSTAT (BASE+6) 

/* line control register base+3*/ 

Idefine DLAB 0x80 /* divisor latch enable */ 
/* modem control MODEMCTL base+4 */ 

Idefine LOOPS 0x10 /* should be low */ 
Idefine GP0UT2 8 /‘card intrp enable? high 
Idefine RTS 2 /* request to send */ 

Idefine GP0UT1 4 /* oncard reset? keep low 

Idefine RTS 2 /* request to send */ 

Idefine DTR 1 /* data terminal ready */ 

/* Modem status M0DMSTAT base+6 */ 


/* carrier detect input*/ 

/* ring indicator input*/ 

/* data set ready inpu */ 

/* clear to send input */ 

/* change in carrier detect*/ 
/* change in ring indicator*/ 
/* change in data set ready */ 
/* change in clear to send */ 


Idefine DC0 0x80 
Idefine RI 0x40 
Idefine DSR 0x20 
Idefine CTS 0x10 
Idefine DDCD 0x08 
Idefine DRI 0x04 
Idefine DDSR 0x02 
Idefine DCTS 0x01 
/* line status reg LINESTAT base+5 */ 

Idefine FRE 0x80 /* rx FIFO has error */ 
Idefine TXE 0x40 /* tx shift reg empty */ 
Idefine TBE 0x20 /* tx buffer empty */ 
Idefine BREAK 0x10 /* break detected */ 
Idefine FE_ERR 0x08 /* rx framing error */ 
Idefine PE_ERR 0x04 /* rx parity error */ 
Idefine 0E ERR 0x02 /* rx overrun error */ 
♦define RXRDY 0x01 /* input data rdy */ 


typedef struct ( 

char line,modem;/* register values */ 
int inbufc.outbufc,overflow; 

) C0M_STAT; 
typedef struct ( 

unsigned abase,divisor; /‘address, divisor */ 
char fifo.datin,line,modem; 

) COM; 

typedef struct ( 

char ‘buffer, *next_in,*next_out,*end_que; 
int buff cnt,overflow; 

” ) CQUEUE; 

/*-end serialc.h-*/ 
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Listing 2 (uartdvr.c) 

/* Uart Driver Program for NS16550 

written by: Charles B. Allison, ATS 
Last Change: 5-8-92 09:30 */ 

J-k *********************** V*********** */ 

llnclude <con1o.h> 
llnclude <stdio.h> 
linclude <dos.h> 
llnclude <bios.h> 
linclude "serialc.h" 

Ipragma intrinsic (inp.outp/*,enable,disable*/) 

/*-defines-*/ 

Ideflne RBSIZE 4100 
Idefine TBSIZE 3256 
Idefine TESTFIF0 1 
Ipragma pack(l) 
static COM com_ch; 

CQUEUE tx; /* transmit queue ptrs */ 

char tbuffer[TBSIZE]; 

CQUEUE rx; /* rx queue ptrs */ 

char rbuffer[RBSIZE]; 

/*-serial port parameters-*/ 

int port addr[6] * (0.COM1,COM2.COM3,COM4,0 }; 
int portjnt[6] * {0,IRQ4,IRQ3,IRQ4,IRQ3,0 }; 

/*... prototypes-*/ 

static void Interrupt far comint(void); /*1nt rtne */ 
/* prototypes for Interrupt sub functions */ 
static void 1rs232(int base); /* ctl line change */ 
static void itxrdy(int base); /* tx intr 1 */ 
static void irxrdy(1nt base); /* rx intr 2 */ 
static void iserr(int base); /* break or error 3 */ 
char ser_mode(1nt sel.long baud,char chr_len, 

char num_stops,char parity); 
void 1n1t_com_bufs(vo1d); 

Int ser_read(char *destbf,int rcount); 
int ser wr1te(char *srcbf,int rcount); 

Int ser”stat(C0M_STAT* st); 

lifdef TESTFIF0 “ 

static Int maxf1fo=l,fifocnt=0; 

lendif 

/* ************comnun1cations interrupt************ */ 
static void interrupt far comint(void) 

{ 

int Intflag; 

int base = com_ch.abase; 

static void (*isr[4]) (int base) * /*array of 

pointers to Interrupt type handlers */ 

{ 

1rs232, /* rs232 input change HR = 0 */ 
itxrdy, /* transmit Interrupt = 1 */ 

Irxrdy, /* receive interrupt =2 */ 
iserr, /* break or error = 3 */ 

}; 

lifdef TESTFIF0 
fifocnt = 0; 
lendif 

whi1e( ((intflag = inp(INTID) & 0x07 ) & 0x01) == 0 ) 

{ /* loop thru all pending 

interrupts (bit 1 = 0) */ 
intflag »= 1; /* get bits 0x02 and 0x04 

bit 3 for nsl6550 don't care*/ 
(*1sr[intflag]) (com_ch.abase); 

/* call routine handler */ 

} /* end of while */ 

outp(PIC00,E0I); /* eoi clear int mask for 
PIC 0 1st int */ 

lifdef TESTFIF0 

If(fifocntxnaxfifo) maxfifo * fifocnt; 
lendif 

I 

/* ** Communications Interrupt subfunctions ** */ 

/*-rs232 changes-*/ 

static void irs232(int base) 

/* rs232 input change IIR = 0 */ 

< 

int tmp; 

com_ch.modem =(char) inp(MODMSTAT); 

/* get modem flags dcts.ddsr, 
dri.dcd cts,dsr,ri,cd */ 

) 

Jk ********************************** kf 

void 1txrdy(int base) /* transmit Interrupt * 1 */ 

{ 

int cnt = com_ch.fifo; /* get fifo size */ 
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operate at a particular baud rate. My 386SX-16 tends to use 
about ten FIFO character slots when running a QuickC-com¬ 
piled version of the program at 115,200 baud. 


Conclusion 

You can readily enhance the serial library provided in this 
article in different ways. You could add support for multiple 
serial channels and special hardware configurations, or en¬ 
hance and tailor error detection and processing code for your 
application. By creating a main program with TSR code and a 


—Cont’d 

outp(DIVMSB,(char)((com_ch.divisor) » 8)); 
outp(LINECTL,com ch.line); /* set line */ 
outp(MODEMCTL,(inp(MODEMCTL))| DTR| GP0UT2); 
inp(RXD); /* clear out existing ints */ 
inp(INTID); 
inp(LINESTAT); 
inp(MODMSTAT); 

_enable(); 
return com ch.line; 

} 

static void (interrupt far *oldint)(void); 
static char irqmask; 

/* ********* se t fnt ******* */ 

void set int(int~sel) 

{ 

unsigned base = port_addr[sel]; 
oldint * _dos_getvect(IRQ_OFF+port_int[sel]); 
_dos_setvect(JlRQ_0FF+port_int[selJ),comint); 
irqmask = (char)( inp(PICOl) & (l«port_int[sel])); 
_disable(); 

outp(PIC01,(inp(PIC01)& ~((char)(l«portJnt[sel])))); 

/* unmask int c *7 

outp(INTEN.OxOf); /* enable all sources */ 

inp(RXD); /* clear out any existing intreqs */ 
inp(INTID); 
inp(LINESTAT); 
inp(MODMSTAT); 

outp(PIC00,E0I); /*clear any 8259A request*/ 
_enable(); 

T 


Listing 2 

if(tx.buff cnt) 

{ 

while((cnt—) && (tx.buff cnt)) 

{ 

tx.buff_cnt~; 
outp(TXD,*tx.next_out); 
if((++tx.next_out) >= tx.end_que) 
tx.next_out = tx.buffer; 

} /* end of while */ 

) /* end of if */ 

1 

/* *********************************** *i 

void irxrdy(int base) /* receive interrupt = 2 */ 

{ 

com_ch.1ine|= (char)inp(LINESTAT) & 0x9e; /* error 
flags oe pe fe */ 

*rx.next_in = com_ch.datin =(char) inp(RXD); 
if(rx.buff_cnt < RBSIZE) 

{ 

rx.buff_cnt++; /* another char to buffer cnt */ 

} else T 

rx.overflow++; /* rx buffer overflow error */ 

} 

if((++rx.next_in) >= rx.end_que ) 

rx.next_in = rx.buffer; /* set to begin que*/ 

#ifdef TESTFIFO" 

fifocnt++; 

lendif 

i 

/*-line errors - */ 

static void iserrfint base) /* errors HR » 3 */ 

1 

com_ch.line |=(char) inp(LINESTAT) & 0x9e; 

I ' 

I * ********************* */ 

/* -set mode-*/ 

char ser_mode(int sel.long baud,char chr_len, 

char num stops,char parity) 

{ 

char tmp.line; 
int divisor; 

unsigned base = port_addr[sel]; 
com_ch.abase = base; 

com_ch.line = (chr_len-5) | ((num_stops-l) «2); 

/* now add stopbits*/ 

tmp = 0; 
switch(parity) 

{ 

case ’S'; 
tmp++; 
case 'M': 
tmp++; 
case 1 E *: 
tmp++; 
case 'O': 
tmp++; 
case 'N': 
default : 
break; 

} /* end of switch */ 

if (tmp) tmp = ((—tmp « 1) | 1) « 3; 

/* lsb set if any parity*/ 
com_ch.line |= tmp; /* put in parity */ 
confch.divisor = (unsigned)(MAX_BAUD/baud); 

_disable(); 

outp(FIF0C,0x07); /* enable FIFOs, reset, trigger 
on 1 byte in receive buffer */ 
if((inp(INTID) & OxfO) == OxcO) 

{ 

com_ch.fifo = 16; /*yes UART is NS16550*/ 

} else { 

com ch.fifo = 1; 

} 

outp(LINECTL,(DLAB|com_ch.line)); 

/* enable divisor latch */ 
outp(DIVLSB,(char)((com_ch.divisor) & 255)); 


FullShot 
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Q Choose hotkeys interactively (see below) 

Q| Capture a full screen or any part of a screen 
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BlOS-style register-oriented INT interface, you could create a 
resident serial port driver, which could alleviate some of the 
problems one encounters when debugging programs with inter¬ 
nal hardware interrupts. Such a driver could possibly be devised 
as a replacement for the polled BIOS serial port interface. □ 
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Listing 2 — Cont’d 


j-k ********* cl r” i nt ******* *y 
void clr_int(int sel) 

{ 

unsigned base = port_addr[sel]; 

outp(M0DEMCTL,0x00); /* clear DTR, card interrupts */ 
outp(PIC01,(inp(PICOl)| (char) irqmask ) ); 
dos_setvect((IRQ 0FF+port_int[sel]),oldint); 

T 

/*.ini t_com_bufs.*/ 

void init_com_bufs(void) 

( 

/* setup and clear out circular buffers */ 
tx.buffer = tbuffer; /* transmit buffer */ 
tx.end_que = &tbuffer[TBSIZE]; 

tx.next_out =tx.next_in = tbuffer;/* tx buf ptrs */ 
tx.buff_cnt = rx.buff_cnt = 0; /* num chars in bufs */ 
rx.buffer = rbuffer; /* receive buffer */ 
rx.end_que = &rbuffer[RBSIZE]; 

rx.next_out = rx.next_in = rbuffer; /* rx buf ptrs */ 
rx.overflow = 0; /* receive buffer over flow*/ 

I 

/*.read rx buffer-*/ 

int ser_read(char *destbf,int rcount) 

{ 

int cnt_read = 0; 

int tmp_buf_cnt = rx.buff_cnt; 

whi1e( (rcount-- ) && (tmp_buf cnt--)) 

{ 

*destbf++ = *rx.next_out++; 
if((rx.next_out) >= rx.end_que ) 

rx.next_out = rx.buffer; /* set to begin que*/ 

cnt_read++; 

} 

_disable(); /* must not risk change in intrpt too */ 
rx.buff_cnt -= cnt_read; /* adjust buffer*/ 

_enableQ; 
return cnt_read; 

i 

/*-write tx buffer-*/ 

int ser_write(char *srcbuf,int tcount) 

{ 

int wrt_cnt = 0; /* number written */ 

int tmp_buf_cnt = tx.buff_cnt; 
int base = com_ch.abase; 

while((tcount--) && ((tmp buf_cnt++) < TBSIZE) ) 

( 

*tx.next_in++ = *srcbuf++; 
if((tx.nexMn) >= tx.end_que) 
tx.next_in = tx.buffer; 

wrt cnt++; 

} 

_disable(); /* must not risk change in intrpt too */ 
tx.buff_cnt += wrt_cnt; 

if(inp(LINESTAT) & 0x60) itxrdy(com_ch.abase); 
_enable(); 
return wrt_cnt; 

} 

/*..get status..*/ 

int ser stat(C0M STAT* st) 

{ 

st->line = com_ch.line; 

st->modem = com_ch.modem; 

st->inbufc = rx.buff_cnt; 

st->outbufc = tx.buff_cnt; 

st->overflow = rx.overflow; 

rx.overflow = com_ch.line = 0;/* clear errors */ 

return rx.buff cnt; 

} 

/*- S et modem controls-*/ 

int ser con(int states,int masks) 

( 


int base = com_ch.abase; 
int tmp = 0; 

/* masks enables changes for bits 

6P0UT2 should be high, - enables card interrupts 

DTR, RTS, user modifiable 

LOOPS, GP0UT1 should be low for normal operation */ 
outp(M0DEMCTL,tmp =((inp(M0DEMCTL) & "masks) | 

(states & masks))); 

return tmp; 

} 

Idefine LINEL 3128 

char 1inebuf[LINEL +1]; /* output line buffer */ 
char inbuf[LINEL+1]; 

/* set PORT = COM2 */ 

Idefine PORT 2 

y* ************* ******************* + j 

/* dumb terminal example use */ 
int main(void) 

{ 

char tmp; 

int dline = 0,itmp,incnt,outcnt=0; 

C0MJTAT cst; 

printf("FIF0 Usart Example\n ESCape to exit \n H ); 

1nit_com_bufs(); /* initialize buffers */ 

serjnode(PORT,115200L,8,1.'N'); 

set_int(P0RT); /* setup int vectors */ 

itmp =GP0UT2+DTR+RTS; /* set line control reg. */ 

ser_con(itmp,(itmp+GPOUTl)| LOOPS); 

for(;;) /* main loop */ 

( 

if(_bios_keybrd(_KEYBRD_READY)) 

{ /* output a Tine at a time */ 

tmp = (char)_bios_keybrd(_KEYBRD_READ); 
if(tmp != 0) 

{ 

putch(tmp); 

if(tmp == '\xlb') break; /*break on ESC */ 

1f((tmp == '\r') || (outcnt >= (LINEL-1) )) 

( 

printf("\n M ); 
linebuf[outcnt++] = *\n'; 

1inebuf[outcnt] = '\0 1 ; 
ser_write(linebuf,outcnt); 
outcnt = 0; 

} else { 

1inebuf[outcnt++] = tmp; 

1inebuf[outcnt] = '\0 1 ; 

} 

} 

} 

if( (incnt = ser_stat(4cst)) ) 

{ 

itmp = (incnt < LINEL)? incnt;LINEL; 
ser_read(inbuf,itmp); 

Inbuf[itmp] = '\0 1 ; 
printf(“%s",inbuf); 
inbuf[0] = '\0'; 
dline = 0; 
incnt = 0; 

} 

) /*end of loop */ 

/* clean up for exit */ 

clr int(PORT); /* restore int vector */ 

lifdef TESTFIF0 

printf("\nfifo buffer size = %d\n \ 
max char count (in a single interrupt) = %d\n M 

,com_ch.fifo.maxfifo); 

lendif 

exit (com^ch.fifo); 

}/* end of main */ 

able FIFOs, reset, tr 

/* End of File */ 
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Windows WEP Problems 


Brent Rector 


Many Windows programmers consider DLLs difficult to understand or 
write and so avoid creating them. Actually, DLLs differ from Windows 
applications mainly in two respects: a different compilation option is re¬ 
quired because DS != SS; and a special function, the Windows Exit Pro¬ 
cedure (WEP), must be present in every DLL for versions of Windows 
prior to 3.1. 

Enough has been said about the DS != SS issue in other sources, but 
little has been written about how to write the WEP for a DLL. Because 
Windows calls a DLL's WEP function when Windows is unloading the DLL, 
the WEP function would seem the obvious place to put code that cleans 
up after the DLL - releasing resources, freeing memory, etc. 

Actually, you do not need to free global memory in a WEP function 
because Windows automatically frees global memory owned by a DLL. 
(This is convenient because, as you’ll see shortly, you may not be able to 
call the GlobalFree function!) However, you might like to use the WEP 
to free GDI objects created by the DLL, such as brushes, pens, bitmaps, 
etc. Unfortunately, under Windows 3.0, the WEP function is, for all intents 
and purposes, useless, because Windows calls it in such a way that you 
can't reliably call any Windows functions. 

Here is a not-so-short list of the restrictions and quirks associated 
with using a WEP function: 

1. Under Windows 3.0, you cannot call most Windows functions from a 
DLL's WEP function. Windows calls the WEP function while running on a 
KERNEL stack that is too small to allow practically any Windows function 
to be called. 

2. Under Windows 3.0, you cannot call any DOS function from a DLL’s 
WEP function. Calls to DOS functions are intercepted by the Windows 
KERNEL and can also result in an overflow of the KERNEL stack. 

3. Under Windows 3. 1, Windows calls the WEP function on the stack of 
the application that is terminating. This means you can reliably call Win¬ 
dows and DOS functions from a Windows 3.1 DLL's WEP function (subject 
to some of the following additional constraints). 


Brent Rector is an independent computer consultant with his 
own firm, Wise Owl Consulting, Inc. The firm specializes in sys¬ 
tem software design, development, and consulting. Mr. Rector 
has a B.S. in Computer Science from California State University 
at Northridge and has 20 years of computer system design 
and programming experience. He has written numerous com¬ 
pilers, interpreters and operating systems. He is the author of 
the Windows programming book Developing Windows 3 Ap¬ 
plications, Prentice Hall, ISBN 0-672-22802- 5. He can be reached 
on CompuServe at 76414,211. 
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4. Under Windows 3.0, in certain low-memory conditions, 
Windows may call Che WEP function before it has created the 
DLL's data segment When the code in a WEP function acces¬ 
ses static or global data, you must first check to see if the 
library’s default data segment has been loaded. 

This is a bit trickier than it first appears; you can't simply 
check for a zero selector. The DS register always contains a 
valid selector even when the selector refers to a data seg¬ 
ment that has not yet been created. You must check to see if 
the data segment is present by using a lar instruction and 
checking the present bit When the present bit is set, the data 
segment has been created, is loaded, and may be accessed. 

5. Under Windows 3.0, in certain low-memory conditions, 
Windows may call the WEP function before it has called the 
LibMain function. This can cause problems if your WEP function 
expects certain initialization to have been performed by the 
LibMain/LibEntry functions. To handle this situation properly, 
you'll need to have the initialization code set a flag in the 
default data segment that the WEP function can check. Only if 
the flag is set should you execute the code dependent on the 
library's initialization code. 

6. Under all versions of Windows, you must declare the 
WEP function in the EXPORTS section of a DLL’s module-defini¬ 
tion file and you must specify the RESIDENTNAME keyword. You 
can assign any ordinal number to the WEP function. Here is an 
example statement: 

WEP @42 RESIDENTNAME 

Adding the RESIDENTNAME keyword to the EXPORTS statement 
forces Windows to keep the name/ordinal information about 
the WEP function resident in memory at all times. Windows 
calls the WEP function by name and so must search the DLL's 
name table(s) to determine its ordinal number. 

in certain low-memory conditions, the nonresident name 
table (where the function name resides when you omit the 
RESIDENTNAME keyword) may be discarded from memory. In 
order to call the WEP function, Windows must first reload the 
nonresident name table and that reload might fail, causing a 
fatal exit. The RESIDENTNAME keyword instructs Windows to 
keep the name/ordinal information about the WEP function in 
the resident name table, which always remains in memory. 

7. Under Windows 3.0, the WEP function must be placed in 
a fixed-code segment of the DLL. Windows 3.0 considers all 
movable code segments discardable, whether or not you use 
the DISCARDABLE keyword on a SEGMENTS statement in the 
DLL’s module-definition file. Marking the code segment con¬ 
taining the WEP function as FIXED tells Windows it isn't mov¬ 
able and, therefore, isn't discardable. 

In certain low-memory conditions, if you did not mark the 
segment containing the WEP function as FIXED, Windows 
could discard the segment before it needs to call the WEP 
function. If Windows is unable to reload the segment, a fatal 
exit occurs. 

All versions of Windows page-lock DLL segments that are 
marked FIXED, so you should place as little code as possible 
in a fixed segment. Windows 3.1 honors the memory options 


specified for DLL segments by regarding segments marked 
movable but not marked discardable as not discardable. 

8. With some debuggers, the WEP function of implicitly 
loaded DLLs may not be called until after the debugger indi¬ 
cates that the application has terminated. On a related note, if 
you release certain Windows resources such as brushes and 
pens in a WEP function of an implicitly loaded DLL, the Win¬ 
dows debug version may report that the resources have not 
been freed. The debug version checks for unreleased resour¬ 
ces after the application has terminated but before all WEP 
functions have been called. The resources are correctly 
released. 

9. The WEP functions in a set of interrelated DLLs can be 
called in any order. Windows calls a WEP function when its 
reference count reaches zero. Windows calls the WEP function 
of a DLL loaded by a call to the Load Library function when 
you call the Free Library function (assuming the DLL's refer¬ 
ence count is then zero). Windows calls the WEP function of 
an implicitly loaded DLL when the DLL’s reference count 
reaches zero, implicitly loaded DLLs may not be freed in the 
same order in which they were loaded. 

10. The module name specified on the LIBRARY statement 
in a DLL’s module-definition file must not contain lowercase 
letters. The module name must be identical to the file name. 
The module name has the same naming restrictions as do 
other file names on a given system. Under FAT file systems, 
this means that module names are restricted to a maximum 
of eight characters, all of which must be valid for use in a file 
name. 

11. You cannot call the FreeLibrary function from the WEP 
function. The FreeLibrary function (or Windows' internal 
equivalent) calls the WEP function and FreeLibrary is not re¬ 
entrant. 

12. You cannot close fles or flush file buffers from the WEP 
function of a DLL. Files are owned by tasks (applications), not 
by DLLs. By the time Windows calls the WEP function, the task 
has terminated and all open files have been closed. 

If you are using the Microsoft C/C++ 7.0 compiler, the 
standard runtime library for DLLs (e.g., MDLLCEN. LIB) contains 
an already written WEP function. The C runtime WEP performs 
several cleanup functions when Windows unloads a DLL from 
memory (for example, it releases memory and calls atexit 
routines). You can extend the library WEP function with your 
own termination code by placing the code in a function called 
_UEP. The standard C runtime WEP function returns to Win¬ 
dows the return value of the _UEP function. The Microsoft C 
7.0 runtime WEP function will call your JlEP function if you've 
written one. The _UEP function has the following form: 

int _far _pascal _WEP (int nParameter) ; 

Summary 

WEP functions were a source of problems and confusion 
for Windows 3.0 programmers. They still have some caveats, 
but with this set of guidelines and Windows 3.1 in hand, you 
can finally write useful, reliable cleanup routines for your DLLs. □ 
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A Loader Program for 3.0 Installs 


Q I have developed an install program for Windows to transfer the files from my 
floppies to my hard disk. The install program is on the first disk of a set and is 
to be run via the Program Manager's Alt+F+R sequence. 

I found that when the install program prompts for a disk change, if the second 
disk has a different label than the first, I get a system error message, explaining that 
the system can't read from the specified disk drive. 

How can I get around this problem other than ensuring all disks of a set have the 
same label? Also, I understand that install programs which automatically create new 
Groups and/or place new programs into the Program Manager do so via a DDE 
process. How is this done and how can I get the specifications? 

Peter D'Agostino 
9285 Lerwick Drive 
Dublin, OH 43017 

A I ran across exactly this problem only a few months ago. At first I thought it 
was due to an attempt to access the executable when the floppy containing it 
was not present. So to prevent Windows from reopening the executable, I made all 
code segments PRELOAD, and explicitly loaded and locked all resources during in¬ 
itialization. The problem persisted. It turns out that the problem is due to a bug in 
Windows. 


Paul Bonneau 


Send questions to Paul via Internet 
as bonneau@hyper.hyper.com or in 
care of this magazine at 1601 W. 
23rd St., Suite 200, Lawrence, KS 
66046-2743. 


Paul Bonneau is the senior software design engineer for Hypercube, Inc., # 7-419 Phillip 
St., Waterloo, Ontario, Canada, N2L 3X2. His current project is HyperChem, a molecular 
modelling software package for Windows. Paul has been developing Windows ap¬ 
plications for 5 years. Much of his expertise was gained at Microsoft, where he imple¬ 
mented a library module used by all of Microsoft's major Windows applications. 





















^********* ************* *******************************i 

/* -- Copy the install executable to a hard disk */ 
/* with enough free space. */ 

/* -- Then fork install and exit. */ 

^*****************************************************j 
/***************************************************** j 

/* Header files. */ 

^***************************************************** j 

linclude <windows.h> 
linclude <io.h> 

/*****************************************************/ 


Listing 1 (install.c) 


/* Constants. */ 

/*****************************************************j 

/* Maximum length of a DOS path. */ 

♦define cbPathMax 128 

/* Control ID of StaticText that replaces */ 

/* PushButton. */ 

♦define didlnit 0x1000 

/* Replace with the name of your "real” install */ 

/* program. */ 

Idefine szlnstall "realinst.exe" 

/* (Optional) name of the installation script file. */ 
Idefine szScript "setup.inf" 

j*****************************************************i 

/* Globals. */ 

y***************************************************** y 
/* Put the name of your application here. */ 
char szCaption[] = "MyApp Installation"; 

/* Call name for the main window. */ 
char szClass[] = "Hclnst20"; 

char szHello[] = /* Initial message to user. */ 


Easy Sprite Animation 
for MS Windows 


WANIM.DLL makes it easy to incorporate 
video game animation into your own 
Windows programs. 

□ Use with Visual Basic, C/C++, TPW, etc... 

□ Animate sprites on a colored background within a window. 

□ Great for games, education, multimedia. 

□ Algorithmic or bitmap sprites. Or a combination of both. 

□ Change sprite display priority on the fly. 

□ Background scroll and collision detection. 

□ Maintain multiple animation zones within a window. 

□ Easy to understand user manual. 

□ WANIM.DLL is only $69. With source $99. $5S&H. 

□ No Royalties. Call or write for free demo disk and info. 
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"Welcome to the MyApp installation program. This" 
“ program will install MyApp onto your computer." 

" Please wait while the installation process" 

" begins."; 


BOOL fProceed; 
HWND hwndMain; 


Has USER hit Proceed button? */ 
Main window handle. */ 


/*****************************************************/ 


******************/ 


/* Prototypes. 

/* 

/* Main window procedure. */ 

LONG CALLBACK AppWndProc(HWN0, unsigned, unsigned, 
LONG); 

/* Remove the filename from a path. */ 

VOID GetBaseName(PSTR); 

/* Make a copy of a file. *7 

BOOL FCopyFile(PSTR, PSTR); 

/* Get and process a messge and dispatch it. */ 

BOOL FGetMessage(VOID); 

/* Invoke our hand crafted dialog. */ 

BOOL FPseudoDialog(HANDLE); 

/***************************************************** j 

/* Routines. */ 

I ***************************************************** j 

int FAR PASCAL 

WinMain(HANDLE hi ns, HANDLE hinsPrev, 

LPSTR lszCommand, int wShowWindow) 


/***************************************************** j 

/* -- Entry point. */ 

j*****************************************************j 

{ 

/* Required buffer for OpenFile. */ 

0FSTRUCT ofs; 

/* Name of install executable on floppy. */ 
char szSrc[cbPathMax]; 

/* Name of install executable on hard disk. */ 
char szDest[cbPathMax]; 

/* Name of information file (optional). */ 
char szlnf[cbPathMax]; 

/* Install program invokation line. */ 
char szExec[cbPathMax *2+1]; 

/* Hard drive to install to. */ 

BYTE chOrive; 

/* Describes our main window class. */ 

WNDCLASS wes; 

/* Make sure there is not another instance running. */ 
if (hinsPrev != NULL) 

{ 

MessageBox(NULL, 

"MyApp installation is already running.", 
szCaption, MB_0K | MBJC0NST0P); 
return FALSE; 

} 

/* Register a class for the main window. */ 
wcs.hCursor * LoadCursor(NULL, IDC_ARR0W); 
wcs.hlcon - NULL; 
wcs.lpszMenuName = NULL; 
wcs.lpszClassName * szClass; 
wcs.hbrBackground « C0L0R_WIND0W + 1; 
wcs.hlnstance - hins; 
wcs.style - CSSAVEBITS; 
wcs.lpfnWndProc * AppWndProc; 
wcs.cbWndExtra - 0; 
wcs.cbClsExtra * 0; 

if (!RegisterClass(&wcs)) 
return FALSE; 
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Windows 3.0 apparently leaves the executable file open 
whenever a resource is loaded. Once the program is ter¬ 
minated, the file is then closed. If the executable does not 
contain any resources (a rather unlikely occurrence for a Win¬ 


dows application), then the file is opened and closed on 
demand (as code segments are loaded). 

This becomes a problem only when the executable resides 
on removable media. If the system detects a change in 
removable media when there is an open file on the drive, any 


Listing 1 — Cont’d 


/* Create the greeting dialog (our main window). */ 
if (lFPseudoDialog(hins)) 

( 

MessageBox(NULL, "Out of memory.", szCaption, 
MB_0K | MBJCONSTOP | MB_SYSTEMMODAL); 
goto WinMainExit; 

) 

/* Give other apps a chance to paint. */ 
if (!FGetMessage()) 
goto WinMainExit; 

/* Greet the user. */ 

ShowWindow(hwndMain, wShowWindow); 
UpdateWindow(hwndMain); 

/* Find out where we are being installed from. */ 

/* Easiest way is to ask for name of this module */ 
/* since Windows will return a full path. */ 
GetModuleFileNamefhins, szSrc, sizeof szSrc); 
GetBaseName(szSrc); 

/* Create a path to the real install program. */ 
lstrcat(szSrc, szlnstall); 


/* Flush all discardable segments, just in case */ 
/* there is an open file handle for one of them. */ 
/* This is actually a pretty paranoid thing to */ 

/* do, but paranoia is an asset here! */ 

G1obalCompact(G1obalCompact(0)); 

/* Invoke the real install program. */ 
if (WinExec(szExec, wShowWindow) < 32) 

{ 

/* This is bad. */ 

MessageBox(NULL, 

"Fatal error encountered while installing", 
szCaption, MB_0K | MB_IC0NST0P); 
goto WinMainExit; 

} 

/* Wait around until the real install program is */ 
/* done. We can tell when it dies by polling */ 

/* for its module handle. */ 
for (;;) 

( 

if (!FGetMessage()) 
goto WinMainExit; 


/* Find a fixed disk to temporarily hold a */ 

/* copy of the real install program. */ 
if ((chDrive * GetTempDrive(O)) ■* 'A' || 
chDrive == 'B’) 

( 

MessageBox(NULL, 

"You must have a network or fixed disk to" 

” install MyApp.", szCaption, 

MB_0K | MBJC0NST0P); 
goto WinMainExit; 

) 

/* Find a temp directory on the hard disk, and */ 

/* copy the real install program there. */ 

GetTempFileName(chDrive, "HYP", 0, szDest); 
if (!FCopyFile(szSrc, szDest)) 
goto WinMainExit; 

/* Optional. Copy an installation script file *7 
/* to same temp directory on the hard disk. */ 
GetBaseName(szSrc); 
lstrcat(szSrc, szScript); 

GetTempFileNamefchDrive, “XYZ", 0, szlnf); 
if (!FCopyFile(szSrc, szlnf)) 
goto WinMainExit; 

/* Give the user a chance to read the greeting */ 

/* before invoking the real install program and */ 

/* hiding the greeting. We require the user to */ 

/* hit Proceed to inform us he is ready. */ 
while (IfProceed) 

if (!FGetMessage(J) 
goto WinMainExit; 

/* Remove the greeting window, but don't destroy */ 
/* it, since it is needed to perform process */ 

/* control. */ 

ShowWindow(hwndMain, SW_HIDE); 

/* Create a buffer to hold the path to the real */ 

/* install program on the hard disk, and its */ 

/* command-line arguments. We supply the path */ 

/* to the disk/directory holding the files to */ 

/* install, and the full path of the install */ 

/* script on the hard disk. */ 

GetBaseName(szSrc); 
wsprintf(szExec, "%s %s %s", 

(LPSTR)szDest, (LPSTR)szSrc, (LPSTR)szlnf); 


if (GetModuleHandle(szDest) *■ NULL) 
break; 

) 
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ToolsKan - 3D Chart 

Generates 2D & 3D charts such as bar, area, line. More than 30 chart, 
axis and labelling styles to choose from. You can see different views of 
the chart by rotationg about the x- or y-axis or by selecting various 
projection styles. Automatic y-axis rotation adds an animated touch! 
Can serve as a database front-end; will ask application for new data 
only when needed. Supports scrolling for long series of data. 



ToolsKan - Table 

Each column can be configured as a Combobox and set editable or 
display only. It can dynamically show or hide a specific column, and 
change the column width. The table can also serve as a database 
front-end. It maintains a cache of the current range of data and will ask 
the application to supply new data. 

ToolsKan - Status Bar (for context sensitive help) 

Stretchable width fields will resize to fit Progress meter showing (%) of 
completion; date and/or time in Windows’ configured internationalized 
format; and NumLock, CapsLock, ScrollLock key states. 

ToolsKan - Toolbox 

It offers a 3D look and feel with color customization and buttons can be 
grouped: Multiple selection like toggle buttons, Single selection like 
radio button, and No-state action element like push buttons. 



[fgi ILItlll] ToolsKan - Rib bon/I con Bar 

w 3D look and feel with color customization. Integrates Comboboxes, 

Static text with application specified font, and Buttons with toggle, radio, 
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subsequent file I/O for the drive will generate an Invalid disk 
change” critical error. Windows traps this error and displays a 
system modal message box. 

The system detects a change in removable media by com¬ 
paring volume serial numbers or, in the case of floppies for¬ 


matted by a version of DOS prior to 4.0, which do not have 
volume serial numbers, by comparing volume labels. I would 
guess you are using preformatted floppies that were for¬ 
matted for an early version of DOS; thus when you make the 
volume label the same on all floppies, the system cannot 


Listing 1 — Cont’d 


/* More paranoia here. Make sure we yield to the */ 
/* dying app just in case its not completely dead */ 
/* yet. */ 

FGetMessage(); 

WinMainExit: 

/* Clean up. Get rid of the temporary files on */ 

/* the hard disk and kill the main window. */ 
if (OpenFile(szDest, &ofs, 0F_EXIST) != -1) 
unlink(szDest); 

if (OpenFile(szInf, &ofs, 0F_EXIST) != -1) 
unlink(szlnf); 

if (hwndMain != NULL) 

DestroyWindow(hwndMain); 

} 


BOOL 

FGetMessage(VOID) 

/* -- Extract and process a message. 

/* -- Return false if it is the quit message. 


{ 

MSG msg; 


if (hwndMain == NULL) 

return FALSE; /* No receiver! */ 


if (!PeekMessage(&msg, NULL, 0, 0, PM_REM0VE)) 
return TRUE; /* No oustanding events. */ 
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If (msg.message ** WM_QUIT) 
return FALSE; 

/* Even though we don't have a dialog, we can */ 
/* still use IsDialogMessage() to translate */ 

/* keyboard input for navigating controls. */ 
if (IsDialogMessage(hwndMain, &msg)) 
return TRUE; 

TranslateMessage(imsg); 

DispatchMessage(&msg); 
return TRUE; 

} 


BOOL 

FCopyFile(PSTR szSrc, PSTR szDest) 


/* -- Copy source file to destination. */ 
/* -- Get messages during the copy, so system can */ 
/* still respond to user. */ 


{ 

int nfdSrc = -1; 

int nfdDest = -1; 

char szT[cbPathMax]; 

BOOL fVal = FALSE; 

0FSTRUCT ofs; 


/* Open the source file. */ 

if ((nfdSrc = 0penF11e(szSrc, &ofs, OF READ)) =* 
- 1 ) 


wsprintf(szT, 

"Unable to open installation file %s", 
(LPSTR)szSrc); 

MessageBox(NULL, szT, szCaption, 

MB_0K | MB_IC0NST0P); 
goto FCopyFileExit; 

} 


/* Create the target file. */ 
if ((nfdDest = 0penFile(szDest, &ofs, OF CREATE)) 
« - 1 ) 

I 

wsprintf(szT, 

"Error creating installation file %s", 
(LPSTR)szDest); 

MessageBox(NULL, szT, szCaption, 

MB_0K | MB_IC0NST0P); 
goto FCopyFiTeExit; 

} 


/* Copy source to destination. */ 
for (;;) 

( 

int cb; /* # bytes copied. */ 

BYTE rgb[1024]; /* Copy buffer. */ 

if (!FGetMessage()) 
goto FCopyFileExit; 

If ((cb = (int) lread(nfdSrc, rgb, 
sizeof rgb)J > 0 && 

(int)Jwrite(nfdDest, rgb, cb) != cb) 

{ 

wsprintf(szT, 

"Insufficient disk space available for" 

" Installation file %s", (LPSTR)szDest); 
MessageBox(NULL, szT, szCaption, 

MB_0K | MB_IC0NST0P); 
goto FCopyFileExit; 

} 


/* Have we copied it all? */ 
if (cb == 0) 

{ 

fVal = TRUE; 
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detect when a floppy has been changed and the critical error 
is not generated. 

At any rate, your problem appears to have been fixed in 
version 3.1 (I can reproduce it under 3.0, but not 3.1). If you 
must be able to install onto a version 3.0 system, you must 


prevent Windows from opening a resource from an ex¬ 
ecutable that resides on a floppy. The common technique is 
to write a small “loader" program that copies the install pro¬ 
gram to the hard disk. The loader cannot contain any resour¬ 
ces, so if you need anything resembling a dialog, you will 


break; 

} 


If (cb < 0) 

{ 

wsprintf(szT, 

"Error reading installation file %s" # 
(LPSTR)szSrc); 

MessageBox(NULL, szT, szCaption, 

MB_0K | MBICONSTOP); 
goto FCopyFiTeExit; 

} 

} 

FCopyFileExit: 

/* Clean up. Close open file handles. */ 
if (nfdSrc != -1) 

_lclose(nfdSrc); 
if (nfdDest != -1) 

_lclose(nfdDest); 
return fVal; 

} 


VOID 

GetBaseName(PSTR sz) 

y*****************************************************/ 
/* — Strip a file name (if any) from a path. */ 

j ***************************************************** / 

i 

PSTR pch; 

If (!sz || sz[0] == '\0') 
return; 

/* Start at end of string and work to the front. */ 
/* We are done when first delimeter is met. */ 
for (pch = sz + lstrlen(sz) - 1; pch >= sz; pch--) 
if (*pch ■■ || *pch == '/' || *pch == '\\') 

break; 

pch[l] = '\0 1 ; /* Null terminate. */ 

} 


BOOL 

FPseudoDialog(HANDLE bins) 

/*****************************************************j 


/* — Create something that looks like a dialog. */ 
/* — The dialog has a mutli-line StaticText */ 
/* message, and Proceed and Cancel PushButtons. */ 
/* — It also has a StaticText to replace the */ 
/* PushButtons if the user pushed Proceed, to let */ 
/* him know something is happening. */ 
/* -- We can't use a real dialog else Windows will */ 
/* leave this .exe open and we hit the copy */ 
/* problem. */ 


y*****************************************************^ 

{ 

HOC hdc; /* Output surface. */ 

RECT rect; /* Text output rectangle. */ 

RECT rectWindow; /* Dialog window rectangle. */ 
BOOL fOk; /* Error free? */ 

LONG 1; /* System font unit cell. */ 

int yButton; /* Button top location. */ 
int dxScreen, dyScreen; /* Size of screen. */ 

int dxChar, dyChar; /* System font size. */ 

int dxButton, dyButton; /* PushButton size. */ 

int dxClient, dyClient; /* Client area size. */ 

int dxBorder, dyBorder; /* Border size. */ 

if ((hdc = GetDC(NULL)) == NULL) 
goto FPseudoDialogExit; 

fOk = FALSE; /* Guilty 'till proven innocent. */ 

/* Find the dimensions of the system font. This */ 
/* method is easier than GetTextMetrics(). */ 


Listing 1 — Cont’d 


1 = GetDialogBaseUnits(); 
dxChar = LOWORD(l); 
dyChar = HIWORD(l); 

/* Find dimensions of screen, so we can center */ 
/* dialog. */ 

dxScreen * GetSystemMetrics(SM CXSCREEN); 
dyScreen = GetSystemMetrics(SM^CYSCREEN); 

/* Make client area half the width of the */ 

/* screen. */ 
dxClient = dxScreen / 2; 

/* Compute the size of the client area based on */ 
/* the length of the text and the client width, */ 
/* plus space for a pair of buttons at the */ 

/* bottom. */ 

dyButton = (dyChar * 14) / 8; 

/* Given the initial width of the client area, */ 
/* determine the height to accomodate all the */ 

/* text to display. */ 

rect.left * 0; 

rect.right = dxClient; 

rect.top = 0; 

rect.bottom = dyScreen; 

DrawText(hdc, szHello, -1, &rect, 

DT_CALCRECT | DT_W0RDBREAK); 

/* Rect now contains the size of the StaticText */ 
/* that will display the greeting. */ 
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have to craft one by hand. After the install program has been 
copied, it can be invoked with UinExecf). 

Listing 1 is the code for such a loader program. Listings 2 
through 4 are the linker definition file, (empty) resource file, 
and makefile. The loader creates a main window designed to 
look like a dialog. This pseudo dialog has multiline static text 
that contains a greeting message, and “Proceed" and “Cancel" 
buttons. While the pseudo dialog is displayed, the install ex¬ 
ecutable and an optional script file are copied to a temporary 
location on the hard disk. Once the user hits the “Proceed” 
button, the pseudo dialog is hidden, and the install program is 
invoked. The loader uses GetModuleHandle() in a polling loop 


to wait for the install program to complete installation and 
exit When this happens, the two temporary files are removed 
from the hard disk. When the loader invokes the install pro¬ 
gram, it passes the path of the source (usually A:\) and the 
path of the install script. 

The install program and install script are copied to the hard 
disk in chunks, with a call to PeekMessage() inside the copy 
loop. This allows the user to interact with the system while 
the copy is in progress. As a result, the user might push the 
“Proceed" button some time before the copy is complete. To 
provide confirmation that the push was detected, the two 


Listing 1 — Cont’d 


/* Adjust the client rect to have a white space */ 
/* one character wide around the text. Adjust */ 
/* the height to accomodate the PushButtons. */ 
dxClient - dxChar * 2 + rect.right - rect.left; 
dyClient * rect.bottom + (dyChar * 2) + dyButton; 

/* Postion the client area, then inflate to */ 

/* accomodate the border of the main window. */ 
rectWindow.left = (dxScreen - dxClient) / 2; 
rectWindow.right = rectWindow.left + dxClient; 
rectWindow.top = (dyScreen - dyClient) / 2; 
rectWindow.bottom = rectWindow.top + dyClient; 
dxBorder • GetSystemMetrics(SM CXDLGFRAME); 
dyBorder = GetSystemMetrics(SM~CVDLGFRAME); 
rectWindow.left -= dxBorder; 
rectWindow.right +* dxBorder; 
rectWindow.top -* dyBorder; 
rectWindow.bottom +* dyBorder; 

/* Create the main "dialog" window. */ 
if ((hwndMain * CreateWindow{ 
szClass, 

NULL, 

WS_DLGFRAME | WS_P0PUP, 

rectWindow.left, 

rectWindow.top, 

rectWindow.right - rectWindow.left, 
rectWindow.bottom - rectWindow.top, 

NULL, 

NULL, 

hins, 

NULL)) — NULL) 
goto FPseudoDialogExit; 

/* Create the multi-line StaticText to hold the */ 
/* greeting. */ 
if (CreateWindow( 

"static", 

szHello, 

WS_CHILD | WSVISIBLE. 

dxChar, 

dyChar / 2, 

rect.right, 

rect.bottom, 

hwndMain, 

- 1 , 

hins, 

NULL) — NULL) 
goto FPseudoDialogExit; 

/* Size the PushButtons to be the width of the */ 
/* text, but allowing a one character wide gap */ 
/* between them. Postion them one character */ 

/* below the multi-line StaticText. */ 
dxButton * (rect.right / 2) - dxChar; 
yButton ■ rect.bottom + (dyChar * 3) / 2; 

/* Create the PushButtons. */ 
if (CreateWindow( 

"button", 

"iProceed", 

WS CHILD I WS_VISIBLE | WS TABSTOP | 

BS_DEFPUSHBUTTON, 

dxChar, 


yButton, 

dxButton, 

dyButton, 

hwndMain, 

IDOK, 
hi ns, 

NULL) — NULL) 
goto FPseudoDialogExit; 

if (CreateWindow( 

"button", 

"{.Cancel", 

WSCHILD | WS VISIBLE | WS TABSTOP | 
BS_PUSHBUTTON, 
dxButton + (3 * dxChar), 
yButton, 
dxButton, 
dyButton, 
hwndMain, 

IDCANCEL, 

hins, 

NULL) — NULL) 
goto LPseudoDialogExit; 

/* Create the StaticText to replace the */ 

/* PushButtons if the user hits Proceed. */ 
if (CreateWindow( 

■static", 

"Initializing...", 

WS_CHILD | SS_CENTER, 

dxChar, 

yButton, 

(dxButton + dxChar) * 2, 

dyButton, 

hwndMain, 

didlnit, 

hins, 

NULL) — NULL) 
goto FPseudoDialogExit; 

fOk = TRUE; 

FPseudoDialogExit: 

/* Clean up. */ 

if (!fOk && hwndMain != NULL) 

( 

/* There was an error, so get rid of main */ 
/* window. */ 

DestroyWindow(hwndMain); 
hwndMain = NULL; 

) 

if (hdc != NULL) 

ReleaseDC(NULL, hdc); 

return fOk; 

) 

LONG FAR PASCAL 

AppWndProc(HWND hwnd, unsigned wm, unsigned wParam, 
LONG IParam) 
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Listing 1 

— Cont’d 

^*****************************************************i 

SW HIDE); 

/* -- Pseudo dialog's window proc. */ 

ShowWindow(GetDlgItem(hwnd, didlnit), 

!***************************************************** i 

SW_SH0WNA); 

i 

switch (wm) 

/* Change class cursor to hourglass, so */ 

{ 

/* it will show only this app is busy. */ 

default: 

SetClassWord(hwnd, GCW HCURS0R, 

break; 

LoadCursor(NULL, IDC_WAIT)); 
break; 

case WM SETF0CUS: 


/* Set focus to Proceed button if main */ 

case IDCANCEL: 

/* window gets focus. */ 

DestroyWindow(hwnd); 

SetFocus(GetDlgItem(hwnd, ID0K)); 

break; 

break; 

) /* End switch wParam. */ 

return OL; /* End case WM COMMAND. */ 

case WM COMMAND: 


switch (wParam) 

case WM 0ESTR0Y: 

1 

hwndMain = NULL; 

default: 

break; 

return 

} /* End switch wm. */ 

DefWindowProc(hwnd, wm, wParam, IParam); 



return DefWindowProc(hwnd, wm, wParam, IParam); 

case ID0K: 

) 

fProceed = TRUE; 


/* User hit proceed. Replace */ 

/* End of File */ 

/* PushButtons with StaticText so he */ 

/* knows something is happenning. */ 
ShowWindow(GetDlgItem(hwnd, ID0K), SW_HIDE); 
ShowWindow(GetDlgItem(hwnd, IDCANCEL), 
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Listing 2 (install.def) 

;; — Linker definition file 

for install loader. ;; 

*>; program. 


NAME 

Install 


DESCRIPTION 

'Install 1 


EXETYPE 

WINDOWS 


STUB 

'WINSTUB.EXE' 


CODE 

PRELOAD MOVEABLE 

DISCARDABLE 

DATA 

PRELOAD MOVEABLE 

MULTIPLE 

HEAPSIZE 

1024 


STACKSIZE 

10240 


EXPORTS 



AppWndProc @1 



Listing 3 (install.rc) 

^*****************************************************i 

I* -- Just an empty file, so rc won't complain. */ 

/* -- We need to run rc against install.exe so that */ 

/* it will be recognized as a windows 3.x app. */ 

^*****************************************************^ 


buttons are hidden and in their place a single-line of static 
text containing the message "Initializing...” is displayed. 

Before registering a class for the pseudo dialog window, 
the loader makes sure there is not another instance running 
by checking that the previous instance handle is NULL. The 
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Listing 4 (makefile) 

####################################################### 
## -- Project file for install loader program. ## 

####################################################### 
all: install.exe 

install.obj: install .c 

cl -c -AH -G2w -Od -Zdpe -W3 install.c 

install.exe: install.obj install.def install.rc 

link /NOD/m install,,, libw mlibcew, install.def 
rc install 


pseudo dialog is created and displayed and the files are 
copied to a temporary location (i.e., c:\tmp) on the hard disk. 
The program waits until the user has hit "Proceed” on the 
pseudo dialog before invoking the install program. If this step 
was not included, a user on a fast machine might see only a 
quick flash, and be left wondering what piece of perhaps im¬ 
portant information had just been missed. 

As for your second question, the program manager accepts 
five DDE command strings for manipulating program items and 
groups: 

[creategroup(szGroupName)] 

[showgroup(szGroupName, swCommand)] 
[deletegroup(szGroupName)] 

[additem(szCommandLine, "szTitle", szIconFile, 
wlconlndex)] 

[exitprogman(l)] 

The dele teg roup command deletes the named group (given 
by szGroupName). This should be done before creating a new 
group in case the user is reinstalling. The creategroup com¬ 
mand creates a new group of the given name ( szGroupName) 
and make it the active group. The additem command creates 
a new program item in the active group. 

The szCommandLine parameter specifies the path and op¬ 
tional command line arguments to be used when invoking the 
program. The szTitle parameter specifies the title that will 
appear under the icon. The szIconFile parameter names the 
executable that contains the icon resource to use for display¬ 
ing the application. If szIconFile is null, the icon is extracted 
from the executable named in szCommandLine. The wlcon¬ 
lndex parameter is the index of the icon in the executable file 
to use. The showgroup command can be used with a Show- 
Uindow()SW_ command to control the appearance of the 
group window. You may want to minimize the startup group 
(SH_SHOUMINIMIZED) if you added something to it. Finally, the 
exitprogman(l) command causes the Program Manager to 
record the current groups to disk (as group files). 

Establish a DDE communication with the Program Manager 
with NM_DDE_INITIATE, using "PROGMAN” for both the-applica¬ 
tion and topic names. Post the above commands using 
NM_DDE_EXECUTE after the conversation has been established. 
Use UM_DDE_TERMINATE to end the conversation. 

The Program Manager interface was documented in the 
"Windows Development Notes” which Microsoft sold separate¬ 
ly from the 3.0 SDK. This documentation is now included with 
the 3.1 SDK. □ 

Paul Bonneau 
bonneau@hyper.hyper.com □ 
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A Windows assert() 
with Symbolic Stack Trace 


Assertions are an important technique for writing 
robust, correct code. Some languages, such as Eiffel, 
even have built-in support for assertions. C and C++ 
supply assertions in the form of the assert () macro, 
which allows you to place assertions in your code 
and switch assertion checking on or off at compile 
time. 

One problem with assert () is that the informa¬ 
tion assert () supplies when the assertion fails is 
often too low-level to be of much direct use. For ex¬ 
ample, suppose your application has its own 
memory-management package and the function for 
releasing memory looks like this: 



The assertion will detect an erroneous attempt to 
free a NULL pointer. Unfortunately, the information 
assert () prints out looks something like this: 


Matt P/etrek is a developer at a large California tools 
vendor. He specializes in debuggers and file brows¬ 
ing/conversion utilities. He is a co-author of the up¬ 
coming book Undocumented Windows. Matthew lives 
with his wife, April, and their two dachshunds, 
Theodore and Gunther, near the beach. 
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Of course, what you really need to know is who passed 
myfree() the NULL pointer, and your application has probably 
called this low-level function from many different places. Thus, 
although assert () is good at detecting errors, you often end 
up having to load the application into a debugger, execute to 
the failed assertion, and then examine a stack traceback to 
locate the real culprit. 

Wouldn't it be nice if assert () could also supply a stack 
trace with enough symbolic information for you to see what 
was going on when the assertion failed? This article tells you 
how to build a version of assert () that does just that for 
Windows programs. As part of the process, I describe how to 
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read and use .sym files to provide symbolic annotation (where 
possible) for each frame in the stack trace. In addition, I show 
you how to use the new toolhelp.dll to walk the stack, 
saving you from having to write complex, error-prone code to 
walk the stack yourself. Microsoft made toolhelp.dll avail¬ 
able with Windows 3.1, but it also works with Windows 3.0. 

Design Goals 

Six objectives underlie the choices I made in designing this 
improved assert () package. 

First, the implementation should be as similar as possible 
to the standard C assert () macro. Code that uses assert () 
should be able to use the improved w_assert() with just a 
simple name change. 

Second, there should be as little intrusion as possible into 
the code and makefile of the project. To use w_assert(), you 
only need to include one header file, and link with one library. 
By putting the code in a library, you prevent the linker from 
pulling in the w_assert() code if it is not used. If w_assert() 
were a .obj file, then you would have to change the link 
command line to prevent the w_assert() code from always 
being linked in. 

Third, I wanted to avoid the need for an import library. 
w_assert() uses functions in toolhelp.dll. If u_assert() 
called the TOOLHELP functions directly, you would have to in¬ 
clude the TOOLHELP import library every time you linked a 
program that used w_assert(). To avoid this problem, the 
package uses LoadLibraryO to load toolhelp.dll as 
needed. w_assert() calls the TOOLHELP functions through 
function pointers that it obtains by calling GetProcAddress(). 

Fourth, it should be easy to change the format of the stack 
trace information that w_assert() displays. To this end, the 
package contains an information output function that is called 
with a string containing information to be displayed. A second 
parameter tells the output function which of three possible 
states it is in: 

• This is the start of information for this stack trace. 

• This is a continuation of the stack trace. 

• This is the end of the stack trace. 

This lets you change the format of the stack trace without 
going into the internals of the stack-walking code. For in¬ 
stance, you could change the output routine to put the dis¬ 
play strings in a list box and pop up the list box after receiving 
the last string. 
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Fifth, the code for accessing the .sym file should be rela¬ 
tively portable and not tied to the rest of the code. You 
should be able to take the .sym file code and use it in 
another project, without having to drag along any of the other 
w_assert() code. In fact, an ambitious programmer might 
make a C++ class or Turbo Pascal object out of itl 

Sixth, and finally, the code should do appropriate error 
checking, but not be paranoid. This is especially true in the 
. sym file module. The code makes a couple of checks in the 
beginning to make sure it has a valid .sym file. Beyond that, 
however, the code does not check to make sure that every 
file seek or read succeeded, since that would have made it 
more difficult to see the underlying mechanics of reading the 
. sym file. 

.sym Files 

The key to creating this enhanced assert() is the .sym 
file, the "secret sauce” that makes symbolic stack traces pos¬ 
sible. Although not many people are aware of them, .sym files 
are used by many debugging tools. Under DOS, they are used 
by SYMDEB. Under Windows, they are used by the Windows 
Debugging Kernel, HEAPWALK, WINSPCTR (a utility available in 
Borland C++ v3.1), DRWATSON, WDEB386, and other programs. 
Microsoft ships .sym files for the three Windows “core” DLLs 
(USER, KERNEL, and GDI) in the SDK. For your own programs, 
you can create .sym files by running Borland's TMAPSYM on 
Borland-style .map files, or by using Microsoft’s MAPSYM with 
Microsoft-style .map files. If you do not have the source for a 
program or DLL, you can still create .sym files for them by 
using BUILDSYM, from Borland C++ v3.1. 

If you are familiar with more advanced debug information 
formats - such as those TDW and CVW use - you will see 
that their relative simplicity is both the advantage and the 
disadvantage of .sym files. A .sym file can give you at most 
three things: 

• A correlation between an address and a symbol name. 

• A correlation betwen a code address and its source file and 

line number. 

• A correlation between a constant and a symbolic name for 

the constant. 

What is missing from .sym files is symbolic type informa¬ 
tion. For instance, a .sym file cannot indicate that a symbol is 
an int, as opposed to a float, or whether a symbol in a code 
segment is a function or a label. Because there is no way to 
indicate type information, user-defined data types (that is, 
structures) cannot be encoded. Thus, with only a .sym file to 
work from, you cannot ask your debugger to inspect a struc¬ 
ture. To add to the list of negatives, .sym files contain no in¬ 
formation about local variables, because there is no constant 
address for BP-based variables. 

Having beaten up on .sym files, I will now praise them for 
their relative simplicity. Compared to the contortions required 
to read a TDW or CVW symbol table, reading .sym files is a 
dream. And, for problems such as printing stack tracebacks or 
symbolic disassembly, the information in a .sym file is perfect¬ 
ly adequate. Also, creating a .sym file is typically much faster 
than having your compiler produce gobs of symbol table infor¬ 
mation, and then waiting for the linker to process it all. 
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Until recently the .sym file format has been shrouded in 
mystery. With the advent of Windows 3.1, Microsoft has for¬ 
mally documented it in the Windows online help, under the 
topic “FILE FORMATS.” Additionally, TDUMP (from Borland C++ or 
Turbo Pascal) can display both 16- and 32-bit .sym files, if you 
are inclined to go snooping. 

I recommend you read the .sym file documentation in the 
Windows 3.1 SDK, since I will refer to structure names and 
members mentioned in that documentation. Also, for the pur¬ 


Listing 1 (symfile.h) 

// w assertO by Matt Pietrek, 1992 

N 

H 

II 

N 

II 

II 

N 

II 

II 

II 

II 

II 

II 

II 


// A few structure 

declarations derived from 

// the Windows 3.1 

SDK // documentation, with types 

// changed to be more portable and not 

// require WINDOWS. 

H 

typedef struct 
/ 

unsigned short 

ppNextMap; 

unsigned char 

bFlags; 

unsigned char 

bReservedl; 

unsigned short 

pSegEntry; 

unsigned short 

cConsts; 

unsigned short 

pConstDef; 

unsigned short 

cSegs; 

unsigned short 

ppSegDef; 

unsigned char 

cbMaxSym; 

unsigned char 

cbModName; 

) MAPDEF; 

typedef struct 
/ 

unsigned short 

ppNextSeg; 

unsigned short 

cSymbols; 

unsigned short 

pSymDef; 

unsigned short 

segNumber; // wReservedl in the SDK doc 

unsigned short 

wReserved2; 

unsigned short 

wReserved3; 

unsigned short 

wReserved4; 

unsigned char 

bFlags; 

unsigned char 

bReservedl; 

unsigned short 

ppLineDef; 

unsigned char 

bReserved2; 

unsigned char 

bReserved3; 

unsigned char 

cbSegName; 

) SEGDEF; 

typedef struct 

i 

unsigned short 

offset; 

unsigned char 

cbSymName; 

} SYMDEF; 

/* End of File */ 


. sym File Structures 


poses of this article, I assume the goal of reading the .sym file 
is to extract a symbolic name from it, given an address. That 
lets me ignore the information in the . sym file related to con¬ 
stants and line numbers and simplify the example code. 

Translating Addresses to Symbols 

To perform a symbolic stack trace, you need a function 
that, given a “logical" address (the address of a ailing function 
in the stack) and a .sym file, returns the symbol associated 
with that address. As I discussed last month in "Designing a 
Windows Debugger," a Windows logical address is the com¬ 
bination of the module identifier, the order of the segments in 
the executable file, and the offset within the segment. Locating 


Sanity Checks for .sym Files 

Although the main use of the MAPDEF structure is to 
find the linked list of SEGDEFs, the MAPDEF structure is 
also important for sanity checking. Sanity checking is 
necessary to make sure the file really is a . sym file. Many 
file formats store a unique pattern in one or more begin¬ 
ning bytes, just to help programs identify the file type 
correctly. Unfortunately, the .sym file format contains no 
such ID bytes. Worse, Borland's precompiled headers (files 
with a proprietary format unrelated to Microsoft .sym 
files) also use the .sym extension, making it more likely 
that a user might accidentally pass you a bogus .sym file. 

Despite these problems, you can do some rudimentary 
sanity checking with some of the fields in the MAPDEF 
structure. The first is the bFlags field. Bit zero of this field 
is 0 if the file contains 16-bit symbols and 1 if the file 
contains 32-bit symbols; bit one of this field is 1 if the file 
includes an alphabetic symbol table (.sym files contain an 
array of pointers to symbols sorted by their associated 
memory address, but newer .sym files may contain an 
additional, alphabetically sorted, array of pointers to sym¬ 
bols). Since I am not expecting 32-bit symbols, I check to 
see that the bFlags field is equal to either 0 or 2. 

Another sanity check derives from the fact that .dll 
or .exe files can have a maximum of 255 segments. 
Therefore, the MAPDEF cSegs field (the count of SEGDEF 
records) must be less than 256. The MAPDEF field pSeg- 
Entry contains the number of the segment containing the 
entry point, so it must also be less than 256 in a valid 
. sym file. 

As a final check, I use the ppNextMap MAPDEF field to 
locate and read in the LAST_MAPDEF record. The first 
word in that structure must always be zero, so it provides 
a final check for a valid .sym file. □ 
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the symbol in the .sym file that cor¬ 
responds to a particular logical address 
is fairly simple, with only a few 
caveats. 

Figure 1 gives a rough overview of 
the .sym file format, showing the im¬ 
portant parts you have to access to 
translate a logical address into a sym¬ 
bol. Where Figure 1 shows pointers, 
the file will contain file offsets (you 
must read the SDK documentation 
carefully, since some of the file offsets 
are relative to the beginning of the file 
and some are relative to a specific 
record in the file). Even more confusing, 
some of the offsets are “paragraph 
pointers,” which means you must first 
multiply the offset by 16 to obtain the 
correct position in the file. 

Every .sym file starts with a MAPDEF 
structure (see Listing 1). The MAPDEF, 
and the information it indexes to, cor¬ 
responds roughly to one .exe or .dll. 
At its highest level, the .sym file is a 
linked list of MAPDEFs. However, I per¬ 
sonally have never seen a .sym file 
containing more than one MAPDEF, not 
counting the last MAPDEF, which is 
really just an "End of the chain” 
marker. 


Listing 2 (findsym.c) 

7/ -- 

// w_assert() by Matt Pietrek, 1992 

#include <stdio.h> 
linclude <malloc.h> 
linclude "symfile.h" 

// Reads in the first MAPDEF into the address provided to it, and 
// does some basic sanity test to see if the file is "legitimate" 

static int ReadAndVerifySymFileHeader(FILE -symfile, MAPDEF *mapdef) 

{ 

unsigned short nextMap; 

// Seek to the file beginning, and read in the MAPDEF 
fseek(symfile, 0, SEEK_SET); 
if ( !fread(mapdef, sizeof(MAPDEF), 1, symfile) ) 
return 0; 

// A very limited form of sanity checking. The first two test 
// assume the .SYM file is for a Windows program. Those two 
// tests are not relevant for DOS 
if ( (mapdef->pSegEntry > 255) 

|| (mapdef->cSegs > 255) 
j (mapdef->bFlags & 1) 
j (mapdef->bFlags > 2) ) 
return 0; 

// Seek to the next header, which is always the "last MAPDEF" 

// Read in the "next" field, and verify that it's 0 
fseek(symfile, mapdef->ppNextMap * 16L, SEEK_SET); 
fread(&nextMap, sizeof(nextMap), 1, symfile); 


The important fields in the MAPDEF structure are the SEG- 
DEF count (cSegs) and the offset to the first SEGDEF record 
IppSegDef). Symbol information in a .sym file is organized on a 
per-segment basis. Every segment in the .exe or .dll that 
appears in the .map file has a corresponding SEGDEF record in 
the .sym file. Given the offset of the first SEGDEF record, and 
the total number of SEGDEF records, you can iterate through 
each segment definition, looking for the desired address or 
symbol. 

Remember that the goal of reading the .sym file was to 
find the symbol that corresponds to a particular logical ad¬ 
dress. The MAPDEF record is always first in the .sym file and it 
points to the first in a linked list of SEGDEF records. A 
reasonable first step, then, is to chain through the linked list 
of SEGDEF records until you locate the segment corresponding 
to the logical segment number in the logical address. Chaining 
through SEGDEF records is easy: just seek to and read in the 
first one, then use the ppSegDef field (multiple it by 16 first, 
since the “pp” stands for “paragraph pointer") to locate the 
seek offset of the next SEGDEF. 

At this point, I have to discuss a glaring omission in the 
Microsoft documentation - nowhere does it tell you “which" 
segment in the .exe or .dll the SEGDEF corresponds to. I am 
not referring to the segment name, which is given at the end 
of the SEGDEF record. What you need is the logical segment 
number, as given in the .map file. As it turns out, the segment 
number is stored as part of the SEGDEF record, but it is in a 
field called uReservedl in the Microsoft documentation. In 
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Listing 2 — Cont'd 

if ( nextMap != 0 ) 
return 0; 

return 1; 

} 

// Positions the file pointer at the SEGDEF corresponding to the 
// logical segment parameter, 
static int PositionToCorrectSEGDEE 
( 

FILE *symfile, 
unsigned short seg, 
unsigned short cSegs, 
unsigned short ppSegDef 

) 

{ 

SEGDEF segdef; 

// Iterate through all the segdefs 
while ( cSegs-- ) 

{ 

// Seek to the "next" segdef, and read it in 
fseek(symfile, ppSegDef * 16L, SEEK_SET); 
fread(&segdef, sizeof(segdef), 1, symfile); 

// If it's the right SEGDEF, then back up the file 
// pointer, and return success, 
if ( segdef.segNumber »» seg ) 

{ 

fseek( symfile, OL-sizeof(segdef), SEEK_CUR); 
return 1; 

} 

else 

ppSegDef * segdef.ppNextSeg; // Go to the next SEGDEF 

) 

// If we got here, then we didn't find it. Return failure 
return 0; 


// Uses the SEGDEF to look for the nearest symbol that's less than 
// or equal to to the passed in offset. Returns symbol name in “buffer" 
static void GetSymbolNameFromSEGDEF 
( 

FILE *symfile, 
char ‘buffer, 
unsigned short off 

) 

( 

SEGDEF segdef; 

SYMDEF symdef; 
unsigned long segdefBase; 
unsigned short * symbols; 
unsigned short i; 
char tempString [256]; 

// Remember the SEFDEF offset, then read it in 

segdefBase = ftell(symfile); 

fread(&segdef, sizeof(segdef), 1, symfile); 

// Allocate space to hold the the "offset array" 
symbols = calloc(segdef.cSymbols, sizeof(unsigned short) ); 


symfile.h (Listing 1), I renamed the 
field to segNumber to more accurately 
convey its meaning. 

Once you know where the logical 
segment number resides, you can 
quickly skip through the SEGDEF linked 
list, looking for a SEGDEF record that 
corresponds to the logical segment 
number in the logical address. If you 
manage to iterate through all of the 
SEGDEFs, and still have not found a SEG¬ 
DEF that matches the desired segment, 
then the information just does not exist 
in this . sym file. 

Once you find the correct SEGDEF, 
you can search for the symbol (SYMDEF) 
whose offset in that segment most 
closely corresponds to the offset of the 
address you are looking for. A SYMDEF 
record contains the value of the symbol 
(the offset portion of its logical address), 
a length byte, and a variable-length (up 
to 255) array of characters for the sym¬ 
bol name. A SYMDEF structure definition 
looks like this: 

typedef struct { 

WORD wSymVal; 

BYTE cbSymName; 

char achSymName; /* 1st of array 
*/ 

} SYMDEF; 

As Figure 1 shows, the SEGDEF does 
not point directly to the SYMDEF struc¬ 
tures, but to an array of pointers (of¬ 
fsets from the SEGDEF record) to SYMDEF 
structures. The reason for this extra 
level of indirection is to provide a con¬ 
venient index for locating each variable- 
length symbol definition. The entries in 
this array are sorted by the symbols’ 
logical addresses, so you could use a bi¬ 
nary search to search the table more 
quickly for the desired address. 

findsym.c 

findsym.c (Listing 2) contains the 
code to handle the process l just 
described. The public interface to the 
code is via FindSymbol ()-. 
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void FindSymbol( 
char ‘buffer, 

FILE ‘symfile, 
unsigned short seg, 
unsigned short off); 

Given a handle to an open .sym file and 
a logical address (split into the segment 
and offset portions), FindSymbol () lo¬ 
cates the corresponding symbol name 
and copies it into buffer. If no match¬ 
ing symbol is found, FindSymbol () sets 
buffer[0] to 0. 

FindSymbol () uses ReadAndVerify- 
SymFileHeoder() both to fetch the 
MAPDEF record and to verify that the 
file really is a .sym file (see sidebar). 
After reading the MAPDEF, Find¬ 
Symbol () calls PositionToCorrect- 
SEGDEF(), which either seeks to the 
SEGDEF record of the desired logical ad¬ 
dress or returns a failure code. 

After positioning the file pointer to 
the correct SEGDEF, the last remaining 
job for FindSymbol () is to find the 
symbol nearest to the offset of the logi¬ 
cal address by calling GetSymbolName¬ 
FromSEGDEF (), passing it the .sym file 
pointer, a character string buffer to fill 
in with the symbol name, and the of¬ 
fset in the segment to look for. 
GetSymbolNameFromSEGDEF() uses the 
“offset array" to perform a linear search 
of the SYMDEF records. This array is 
sorted in ascending address order, so 
the function simply looks for a SYMDEF 
with a value greater than the desired 
offset, and then backs up to the pre¬ 
vious SYMDEF record. 

If the first SYMDEF record has an of¬ 
fset greater then the desired offset, 
then it is a lost cause, and the function 
simply returns an empty string. Other¬ 
wise, GetSymbolNameFromSEGDEF() uses 
sprintfO to form a printable symbolic 
address such as: 

_MyFunc + 002B 

Note that the address includes the 
distance in bytes between the symbol 


Listing 2 — Cont’d 

if ( !symbols ) 
return; 

// Read in the "offset array" 

fseek(symfile, segdefBase + segdef.pSymDef, SEEK_SET); 
fread(symbols, segdef.cSymbols, sizeof(unsigned short), symfile); 

// Read in each SYMDEF, using the "offset array". Stop when we 
// find one that occurs after the passed in offset, 
for ( i=0; i < segdef.cSymbols; i++ ) 

{ 

fseekfsymfile, segdefBase + symbolsfi], SEEK_SET); 
fread(8.symdef, sizeof (symdef), 1, symfile); 

if ( symdef.offset > off ) 
break; 

) 

// If i==0, then the offset we're looking for is before any 
// of the symbols. If i > 0, then back up one symbol, and 
// format its information into the "buffer" parameter, 
if ( i != 0 ) 

{ 

fseek(symfile, segdefBase + symbols[i-l], SEEK_S£T); 
fread(&symdef, sizeof(symdef), 1, symfile); 
fread(tempstring, symdef.cbSymName, 1, symfile); 
tempString[symdef.cbSymName] « 0; 

sprintf(buffer, "%s + %04X“, tempString, off - symdef.offset); 

} 

// Free the space allocated for the "offset array" 
free(symbols); 


// Given a .SYM file pointer, and a logical address, look up the nearest 
// symbol to that address, 
void FindSymbol 
( 

char ‘buffer, 

FILE ‘symfile, 
unsigned short seg, 
unsigned short off 

) 

{ 

MAPDEF mapdef; 
unsigned short nextMap; 

buffer[0] = 0; 

// Make sure it's a valid .SYM file. Stop if not. 
if ( !ReadAndVerifySymFileHeader(symfile, &mapdef) ) 
return; 

// Position the file pointer to the right segment/SEGDEF. 
if ( !PositionToCorrectSEGDEF(symfile, seg, mapdef.cSegs, 

mapdef.ppSegDef)) 

return; 

// Extract the symbol name. The result is in "buffer" 
GetSymbolNameFromSEGDEF(symfile, buffer, off); 

} 

/* End of File */ 
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Listing 3 (w_assert.h) 

// w_assert() by Matt Pietrek, 1992 

// prototype the _w_assertfail() function, and apply 

// <extern "C"* if doing a C++ compile 

#ifdef _cplusplus 

extern "C" { 
lendif 

void _w_assertfail( char *msg, char *cond, char *file, int line); 

lifdef _cplusplus 

) 

lendif 

// Just a variation on the 'C' assertO macro 
// with changed names 

lifdef NDEBUG 

Idefine w_assert(p) ((void)O) 
lei se 

Idefine w_assert(p) ((p) ? (void)O : (void) _w_assertfai1( \ 

“Assertion failed: %s, file %s, line %d", \ 
Ip, _FILE_, _LINE_ ) ) 

lendif 

/* End of File */ 


Header File for w assertO 


Listing 4 (w_assert.c) 

// w_assert() by Matt Pietrek, 1992 
//---- 

linclude <windows.h> 
linclude <toolhelp.h> 
linclude <stdio.h> 
linclude <dir.h> 
linclude “w_assert.h" 

Idefine START_ASSERT_OUTPUT 0 
Idefine CONTINUE_ASSERT_OUTPUT 1 
♦define END_ASSERT_OUTPUT 2 

// Prototype for FindSymbol() in FINDSYM.C 

void FindSymbol 

( 

char ‘buffer, 

FILE ‘symfile, 
unsigned short seg, 
unsigned short off 

); 

// Given a module handle, and a logical segment/offset, look for a 
// matching .SYM file, and get the symbolic name closest to the address 

static void GetSymbolicName 

( 

char ‘stringBuffer, 

HMODULE hModule, 

WORD seg, 

WORD off 

) 

{ 

char symbol String[256]; // Where FindSymbol will put its info 

char fi1eName[MAXPATH]; // Path to EXE/DLL & .SYM file 

char drive[MAXDRIVE]; 

char dirfMAXPIR]; _ 


address and the target offset. This is 
often important information, as the 
greater the distance between the two 
values, the more suspect the symbol 
name is. For instance, if the target offset 
was in a static function, then the found 
symbol name would be for the closest 
previous “public" symbol. This is be¬ 
cause the linker will only output public 
symbols to the .map file. 

wassert.c 

Listing 3 (w_assert.h) contains the 
interface definitions for the routines in 
w_assert.c (Listing 4). The core routine 

in w_assert.c is the_ w_assertfail() 

function, which is called by the w_as- 
sert() macro. The first action under¬ 
taken is to duplicate the functionality of 
assertf). The standard arguments that 
assertO passes are sent to the generic 

output function _ w_assertfail_out- 

put(), which I discuss later. 

TOOLHELP handles most of the work 
of walking through the stack and ex¬ 
tracting the return address of each 
function on the stack. I use 
StackTraceCSIPFirst() to fetch the 
first stack frame and StackTraceNext() 
to fetch subsequent stack frames (you 
may want to review the Windows 3.1 
SDK documentation for these functions). 
To meet the goal of avoiding the need 

for import libraries,_ w_assertfail() 

accesses these TOOLHELP functions 
dynamically. It does this by calling 
LoadLibrary(), and then calling Get- 
ProcAddressO to obtain the entry 
points of StackTraceCSIPFirst0 and 
StackTraceNext(). 
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When you call StackTraceCSIP- 
First(), you have to pass it some in¬ 
formation about the stack frame you 
want to fetch. Specifically, you have to 
supply the SS, BP, CS, and IP registers. 1 
use the Borland C++ pseudoregisters 
(_SS, _CS, and _BP) to pass these 
registers to StackTraceCSIPFirstO, 
but a bit of inline assembler could per¬ 
form the same job in other compilers. It 
is a minor annoyance to come up with 
the correct value for IP in C, so I just 
pass 0. I can get away with that be¬ 
cause TOOLHELP simply copies these 
register values to the STACKTRACEENTRY 
structure that it returns. Since I plan to 
“throw away” the first stack frame 
anyway, it won’t matter if it contains 
an incorrect value for IP. It is unlikely 
that users will want to see the stack 

frame for_ w_assertfail() in their 

stack trace. 

After fetching and ignoring the first 
stack frame, StackTraceNext() 
retrieves the subsequent stack frames. 
The STACKTRACEENTRY that StackTrace- 
Next() initializes contains all the infor¬ 
mation needed to call FindSymbol () 
and obtain a symbolic address. For each 
STACKTRACEENTRY, I call the local func¬ 
tion GetSymbolicName() to handle the 
details of calling FindSymbol (). To as¬ 
sist GetSymbolicNameO in performing 
its duties, I also send it the logical ad¬ 
dress of the program counter for the 
stack frame. Although TOOLHELP only 
really had to provide the CS:IP for the 
stack frame, it goes the extra mile, and 
provides the module handle and the 
logical segment corresponding to the CS 



Listing 4 — Cont’d 

char fi1e[MAXFILE]; 

char extfMAXEXT], symExt[MAXEXT]; 

FILE ‘symFile; 

// Null out the return buffer, in case we have to abort early 
stringBuffer[0] = 0; 

// Get the path corresponding to the "hModule'' 
if ( !GetModuleFileName(hModule, fileName, sizeof(fileNarae))) 
return; 

// Change the hModule path to have a .SYM extension 
fnsplit(fileName, drive, dir, file, ext); 
strcpyfsymExt, ".SYM"); 
fnmerge(fileName, drive, dir, file, symExt); 

// If we couldn't open the .SYM file, then get out 
if ( (symFile = fopen(fileName, "rb")) == NULL ) 
return; 

// Call FINDSYM.C to look up the symbolic name 
FindSymbol(symbolstring, symFile, seg, off); 

fclose(symFile); 

// Format the output string as “filename seg:offset symbolname" 
sprintf(stringBuffer, "%-8s%-3s %04X:%04X %s", 
file, ext, seg, off, symbolString); 


// Our simple, generic output routine 

static void _w_assertfail_output(char *msg, int mode) 

{ 

strcat(msg, "\r\n”); 

OutputDebugString(msg); 


// Called by the w_assert() macro. Performs traditional assert() 

// actions, then walks the stack and displays the results 

void _w_assertfail( char *msg, char *cond, char *file, int line) 

{ 

HINSTANCE hlnstanceToolhelp; 

STACKTRACEENTRY ste; 
char stringBuffer[256]; 

BOOL ok; 

BOOL WINAPI. (‘lpfnStackTraceNext)(STACKTRACEENTRY FAR *); 

BOOL WINAPI (‘lpfnStackTraceCSIPFirst)(STACKTRACEENTRY FAR *, 

WORD, WORD, WORD, WORD); 

// Take care of the traditional duties of assert() 
sprintf(stringBuffer, msg, cond, file, line); 

_w_assertfail_output(stringBuffer, START_ASSERT_OUTPUT); 

// Load T00LHELP.DLL. Get out if couldn't load 
if ( (hlnstanceToolhelp = LoadLibraryCTOOLHELP.DLL'')) < 32 ) 
abort(); 

// Get the entry points of the two stack walking functions in 
// TOOLHELP. Get out if not found. Note that GetProcAddress 
// takes an hModule, but a hlnstance works just as well. 
lpfnStackTraceCSIPFirst » GetProcAddress( 

(HINSTANCE)hlnstanceToolhelp, “STACKTRACECSI PFIRST" ); 
lpfnStackTraceNext = GetProcAddress( 

(HINSTANCE)hlnstanceTool hel p, “STACKTRACENEXT" ); 
if ( !lpfnStackTraceCSIPFirst || !1pfnStackTraceNext ) 
abort(); 

// Set up and call StackTraceCSIPFirst 
ste.dwSize * sizeof(ste); 

if( (ok = lpfnStackTraceCSIPFirst(&ste, _SS, _CS, 0, _BP)) == FALSE ) 
abort(); 
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value. This allows GetSymbolicName() to construct a logical 
address, which is necessary for looking up symbolic names. 
Each string that is returned from GetSymbolicNome() is passed 
along to_ w_assertfail_output(). 

After iterating through all the stack frames, _w_as- 
sertfailf) cleans up by calling FreeLibraryf) for tool- 

help, dll. Almost finished, it then calls_ w_assertfail_out- 

put(), telling it that there is no more output to come. Finally, 
_ w_assertfail() calls abort() to terminate the program. 

Earlier, we mentioned the GetSymbolicName() function. 
We'll now look at it in more detail. GetSymbolicName]) takes 
the module handle that is passed, and uses GetModuleFile- 
Name to determine the complete path to the EXE/DLL that the 
module was loaded from. Because .sym files are supposed to 


be in the same directory as their associated EXE/DLL, Get- 
SymbolicName() takes the complete path to the EXE/DLL, and 
runs it through _fnsplit() and _fnmerge(), substituting 
“.sym" for the file extension. If a file with the resulting name 
can be opened (via fopen()), then the file pointer, along with 
the logical segment/offset, is sent to FindSymbol(), which is 
in the findsym.c module. Upon returning from FindSymbol (), 
the .SYM file is closed, and an appropriate output string is 
created via sprintf(). 

The last piece of w_assert.c is the_ w_assertfail_out- 

put() function. As implemented here, it simply calls Output- 
DebugStringO to dump the string to wherever Windows is 
sending debug messages. Remember that, by default, Output- 
DebugStringO sends its output to a debugging terminal via 
C0M1. You can either redirect its output 
to a file by placing an Output- 
To=filename statement in the [debug] 
section of your system.ini file, or use 
Microsoft’s DBWIN utility to view the 
output in a window. 

Using w_assert() 

Once you have built w_assert.lib 
(from the supplied makefile w_as- 
sert.mak in Listing 5), you will find it 
very easy to use. In any place where 
you would ordinarily include assert.h 
and use assert]), use w_assert.h and 
w_assert(). When you link, simply add 
w_assert.lib to the library list for the 
linker. You could even add w_as- 
sert.lib to the standard libraries sup¬ 
plied by your compiler vendor. You can 
always compile a version of your pro¬ 
gram without assertion checking just by 
defining the macro NDEBUG, either 
before you include w_assert.h or on 
the command line of your compiler. 

Don’t forget that, to really see the 
benefit of w_assert (), you have to 
have .sym files for the modules that 
show up in the stack trace. Install or 
build the .sym files for the Windows 
kernel, and use MAPSYM or TMAPSYM 
to build .sym files for your own 
projects. 


Listing 4 — Cont'd 


// Get the next stack frame, and loop until no more frames 
ok = lpfnStackTraceNext(&ste); 

while ( ok ) 

( 

GetSymbolicName(stringBuffer, ste.hModule, ste.wSegment, ste.wIP); 
_w_assertfail_output(stringBuffer, CONTINUE_ASSERT_OUTPUT); 

ok = lpfnStackTraceNext(&ste); 

} 

// Free the TOOLHELP library 
FreeLibrary(hlnstanceToolhelp); 

// Nothing else to say. Tell the output function that we're done 
_w_assertfail_output('"', END_ASSERT_OUTPUT); 

// assertO call abort, so we do to. 
abort(); 


/* End of File */ 


Listing 5 (w_assert.mak) 

TOOLS = c:\c\bin # Change this to where the compiler/linker is 

INCLUDE = c:\c\include # Change this to where your standard header files are 

CC = $(TOOLS)\bcc +w_assert.cfg # Change to whatever compiler you use 

# implicit rule for building source files 
.c.obj: 

$(CC) -c ($< ) 

w_assert.lib: w_assert.cfg w_assert.obj findsym.obj 
tlib w_assert.lib +w_assert.obj +findsym.obj 

# create the compiler configuration on the fly. This works with 

# Borlands MAKE. May need to modify for other MAKES 

# Options: 286 code generation, only make _export functions exportable, 

# Set include path to $(INCLUDE) 

w_assert.cfg: w_assert.mak 
copy &&| 

-2 

-WE 

-1 $(INCLUDE) 

| w_assert.cfg 


Makefile for w_assert() 


Summary 

Debugging tools and methods are 
often overlooked because they are 
viewed as being "obscure.’’ However, as 
you can see from this article, the techni¬ 
ques for building your own tools are not 
that far removed from "mainstream” 
programming. I hope this article will in¬ 
spire you to further investigate the uses 
of . sym files, and to use all of the avail¬ 
able debugging techniques. □ 
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Please send us your best 
tricks and hacks —those 
clever pieces of code to 
make things work the way 
they should! You’ll receive 
at least $50 for each tip 
that we print. 

Send your submissions to.- 
Tech Tips 
Leor Zolman 

1601 W. 23rd St, Suite 200 
Lawrence, KS 66044-2743 
or email 

techtips@rdpub.com. 


Focus on Floppies 


This month, for a change, we offer a unifying theme for Tech Tips: interaction 
with floppy drives. Before this month’s Tips, however, I’d like to announce the 
results of the “Rename Tech Tips" contest. As you may recall, several months ago 
I called for suggestions for a new name for this column in light of the recent 
magazine name change. Perhaps I didn't offer a lucrative enough reward, as the 
results were . . . well, underwhelming. The final nod has to go to Murray L 
Lesser, who wrote: 

“Why not leave the column name as Tech Tips (without the extra caps it used 
to carry). Then, after it is discovered that Windows is a merely passing fad and the 
magazine has to be renamed, you will still be in fine shape." 

I had pretty much reached the same conclusion (although not necessarily for 
the same reasons!). Mr. Lesser's subscription has been extended by one year, 
and he is now also the proud owner of a beautiful Windows/DOS Developer’s 
Journal T-shirt designed by our own resident graphic artist, Twyla Watson 
Bogaard. 

So .. . after a pause to catch our breath, we now proceed to this month's Tips. 

Managing Multiple Floppy Drive Letters on a Single-Drive System 


Chris Howe 
8 Squire Village 
Sunderland, MA 01375 

When writing applications that may be used on a single-floppy PC, one 
should be aware of a peculiarity of the system's BIOS - the floppy can be referred to 
as either drive A: or drive B:. This is fine, except for those times when the user 
accidentally or intentionally switches drive letters while running an application. Then 
the BIOS displays the familiar message (B: could be A: in this case), "Insert diskette 
for drive B: and strike any key when ready.” 

This message is always displayed at the current cursor position, most likely 
wreaking havoc on your carefully crafted interface screen and requiring time-con¬ 
suming redraws (especially in graphics model). It also makes an application look 
unprofessional, as if a blatant error has occurred. Indeed, there are few commercial 
software packages that even attempt to deal with this problem. 

Luckily, there is an easy way to avoid this. Listing 1 shows two short Turbo-C 
functions, SingleDrivef) and SetFloppyO , that can be added to your application. 



Leor Zolman has been involved with microcomputer programming for 15 years. He is 
the author of BDS C, the first C compiler targeted exclusively for personal computers. 
Leor's first book, Illustrated C, is now available from R&D Publications, Inc. Leor and 
his family live in Lawrence, KS. 
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Listing 1 

int single_drive_flag; /‘global flag used by SetFloppyO*/ 

/* return 1 if single floppy system, else return 0 */ 

int SingleDrive(void) 

{ 

char FloppyPresent, FloppyNumber; 

FloppyPresent = peekb(0x40,0xl0) & 1; 

FloppyNumber = ((peekb(0x40,0xl0) & OxCO) » 6) + 1; 
single_drive_flag « (FloppyPresent && (FloppyNumber == 1)) ? 1 : 0; 
return single_drive_flag; 

} 

void SetFloppy(char ‘filename) 

{ 

char disk_name; 
if(single_drive_flag) 

{ 

if(filename[l]==':') /‘If a drive was specified,*/ 

disk_name=toupper(filename[0]); /‘get the letter.*/ 
else 

disk_name=getdisk()+0x41; /‘Else get default drive just in case.*/ 
if (diskjiame—'A 1 ) 

pokeb(0x50,4,0); /* Adjust byte at 0050:0004h as needed.*/ 

else if(disk_name=='B') 
pokeb(0x50,4,l); 

) 

) 

/* End of File */ 


Listing 2 

/* See "biosdisk" function in any C compiler manual and the bios.h 

* header file for more information. 

* Compiled with Borland's Turbo C++, v.1.01. 

* 

* Dan Goldberg, 1992 ... 

* trying to make a better CHKDRV.COM (the PC Mag Debug Script). 

*/ 


linclude <stdio.h> 
linclude <dos.h> 
linclude <bios.h> 
linclude <assert.h> 

Idefine DISK_READ 2 

int main(int argc, char *argv[]) 

{ 

int drive, i, j, retry, strt; 
unsigned ch_out, status « 0; 
char buf[512]; 
int head - 0; 
int track « 0; 

int sector = 6; /* double-density diskette value, but method will work 
with any floppy disk */ 

int nsectors ■ 1; 
int e; 

if (argc < 2) 

( 

clrscr(); 

printf(“\nCHKDRV checks if the floppy drive door is openV); 
printf(”or closed, and the physical integrity of the floppyV); 
printf(“diskette media.\n“); 

printf(“\nPlease supply a drive number: 0 for A:, 1 for B:\n“); 
printf(“\ne.g.: chkdrv 0\n"); 

printf(“(this would check the integrity of drive A:)\n“); 

printf(“\n\nDos errorlevel set to l.\n“); 

exit(l); 

) 


□ Request 349 on Reader Service Card □ 
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First, you have to check the number 
of floppy disks actually attached to the 
system. The SingleDrive() function 
accomplishes this by examining an 
equipment status byte stored in the 
BIOS data area at 0040:0010h. Single- 
Drive () needs to be called once in the 
program before any disk I/O occurs, so 
that it can correctly modify the global 
integer single_drive_flag that is 
used by the SetFloppyf) function. 

The SetFloppyf) function takes ad¬ 
vantage of an obscure flag in the BIOS 
data area at 0050:0004h which deter¬ 
mines the current "name” of the floppy 
drive. If this byte is set to 1, DOS will 
think that the floppy was last referred 
to as B:, otherwise it thinks it was 
called A :. Therefore, modifying this byte 
appropriately before initiating disk activity 
will suppress the dreaded “Insert . . 
message. 

To be used effectively, SetFloppyO 
must be called just prior to opening 
each file specified by the user. It can 
also be used for searches and directory 
listings. 


Listing 2 —Cont'd 


e « atoi (argv[l]); 
clrscr(); 
switch(e) 

{ 

case 0: 

drive = 0; 

printf("\nChecking drive A:\n“); 
break; 
case 1: 

drive = 1; 

printf(“\nChecking drive B:\n"); 
break; 
default: 

drive = 0; 

printfO'VnBasd drive number. Checking drive A: as default.\n"); 
printf("Only drives floppy drives A: and B: are supported\n“); 

) 

/* Read sector making up to 3 retries. Retries are 

* necessary to make sure that any error is not due to 

* motor start-up delay. See explanation for error code 

* 80h, below. */ 

for(retry = 0; retry <« 3; retry++) 

{ 

if((status « biosdisk(DISK_READ, drive, head, 
track, sector, nsectors, buf)) == 0) 

( 

printf(“A11 1 s Well. Drive Door Closed and Disk Read 0k.\n"); 
exit(0); 

I 

) 
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Recover your source code from compiled 
applications with the following programs: 


Valkyrie, by Code Works, for Clipper S'87. 

$345.00 

OutFoxPro for unencrypted FoxPro 1.x.. . 

.$149.95 

OutFoxPro2 for unencrypted FoxPro 2.. . . 

.$149.95 

OutFOX for unencrypted FoxBASE+. 

.$149.95 

UEFOX+ unencrypts encrypted FoxBASE+. 
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deFOX for the early FoxBASE II. 
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dCRYPTR for AT dBASE III+ RunTime+ 

.$149.95 

DECODE for AT dBASE II RunTime. 
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Listing 2 — Cont’d 

/* Read failed despite 3 retries. Report error */ 

printf(“\n\nError reading from diskette! status code=%xh\n", 
status); 

switch (status) 

( 

case 0x80: 

printf(“Disk drive failed to respond.\n"); 
printf("Drive Door is probably open!\n“); 
printf(“Dos errorlevel set to 2.\n“); 
exi t(2); 

case 0x40: 

printf(“Could not move to the requested track.\n“); 
printf(“Dos errorlevel set to 3.\n“); 
exit(3); 

case 0x20: 

printf("Disk Controller Failed.\n“); 
printf(“Dos errorlevel set to 4.\n“); 
exit(4); 

case 0x10: 

printf("CRC error.\n“); 

printf(“Dos errorlevel set to 5.\n"); 

exit(5); 

case 0x09: 

printf(“DMA memory transfer error.\n“); 
printf(“Dos errorlevel set to 6.\n“); 
exit(6); 

case 0x08: 

printf(“Data Lost during DMA transfer.\n“); 
printf(“Dos errorlevel set to 7.\n“); 
exit(7); 

case 0x05: 

printf(“Disk Reset Failed.\n“); 
printf(“Dos errorlevel set to 8.\n“); 
exit(8); 

case 0x04: 

printf(“Could not find Sector.\n“); 
printf(“Dos errorlevel set to 9.\n“); 
exit(9); 

case 0x03: 

printf(“Write failure because disk Write Protected.\n“); 
printf(“Dos errorlevel set to 10\n“); 
exit(10); 

case 0x02: 

printf("Address marks failure [can't get disk info].\n“); 
printf(“Disk probably Not Formatted!\n"); 
printf("Dos errorlevel set to ll.\n“); 
exit(ll); 

case 0x01: 

printf("Command unknown to disk 1/0 system.\n“); 
default: 

printf(“Even Microsoft and Borland have no idea.\n“); 
printf(“Dos errorlevel set to 12.\n“); 
exit(12); 

} 

} 

/* End of File */ 



A Cure for Floppy Drive 
Not Ready Errors 


Dan Goldberg 
DEG Consulting Corp. 

239 East 88, #1 
New York, N.Y. 10128 
(212) 369-9507 


Recently, I had to write a Novell 
menu script that prompted the user to 
put a floppy disk in the floppy drive, 
shut the drive door, and continue 
processing. I ran into trouble, however, 
when the user either (1) didn't put the 
disk in the floppy drive; (2) put the disk 
in but didn’t close the drive door; or (3) 
put a disk in the drive at the exact mo¬ 
ment when a tourist on the Great Wall 
of china accidentally stepped on a but¬ 
terfly, causing the disk drive's hardware 
to malfunction (and a Pacific typhoon, 
as well). 

When any of these events occurred, 
the Novell menu script bombed out and 
left the user in DOS because the script 
could not handle the critical error. What 
was I to do? Why not write a C program 
that would check on the condition of 
the floppy drive and the floppy disk in¬ 
serted into it? 

Listing 2 shows the C code that 
checks a floppy drive's status. You can 
execute the program from a DOS batch 
file and jump to a label based on the 
error level it sets. Or, you can embed 
the code within a larger C application. 

Please note that not too long ago PC 
Magazine published a DEBUG script that 
performed the same basic function as 
this program. However, it set error 
levels without informing the user what 
they meant (unless, of course, the user 
had the documentation, which should 
never be assumed). The program shown 
here is much chattier and more com¬ 
prehensive in its identification of 
problems. 

I am sure you will find this program 
useful in your interactions with users 
when they must insert a floppy disk 
into a floppy disk drive. Exiting to DOS 
from a Novell - or any other - menu 
script can be disastrous. How many LAN 
administrators would trust their users in 
DOS, and on the back of a critical error, 
to boot? n 
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New Products 

Industry-Related News & Announcements 


zApp Interface Library Ports to DOS 

zApp for DOS is a C++ user interface library for text-mode 
DOS that is source-code compatible with zApp for Windows, 
Inmark's existing C++ user interface library product zApp for 
DOS provides the same Windows look and feel; all you have 
to do is recompile your Windows zApp program with the 
new DOS version to port the user interface. 

zApp for DOS provides data entry forms for input valida¬ 
tion and dialog box creation, transparent MDI support, auto¬ 
matic window sizing and positioning, logical size and 
dimensioning of objects, and flexible message handling. 
zApp provides facilities for automatic background tasks that 
are executed while the application is idle. 


zApp costs $495 and comes bundled with zApp for Win¬ 
dows (including source code). Inmark offers an unconditional 
60-day, money-back guarantee on all of its products. zApp 
for DOS supports Borland, Zortech, and Microsoft C++ com¬ 
pilers. For more information, contact Inmark Development 
Corporation, 2065 Landings Drive, Mountain View, CA 
94943 (415) 691-9000; FAX (415) 691-9099; BBS (415) 691- 
9990; CIS 70550,2570. 


WinServe Provides DOS-Windows Communications 


Rational Systems, Inc, has released WinServe, a toolkit 
that makes it easier to transform existing DOS programs into 
Windows 3.0 applications. WinServe exploits the multitask¬ 
ing feature of Windows 3.x to split an application into two 
processes: a client and a server. The existing DOS application 
becomes the server, running in an invisible DOS box. Instead 
of writing directly to the screen, the server uses WinServe to 
communicate with a Windows client process. The client, a 
true Windows application, provides the user interfaces and 
communicates with messages (via WinServe) with the DOS 
application. 


In addition to reducing the time needed to make a DOS 
application compatible with Windows, WinServe provides 
shared memory, a standard DLL that exports an API for Win¬ 
dows applications, an object file containing the API for 
DOS/16Mb applications, a built-in debugger, and a Windows 
3.0 virtual device driver (VxD), which provides the DOS-Win¬ 
dows communications mechanism. 

WinServe prices start at $5,000. For more information, 
contact Rational Systems, Inc., 220 No. Main St, Natick, 
MA 01760, (508) 653-6006; FAX (508) 655-2753. 


ToolsKan Provides Custom Controls 

Toolskan is a set of five custom controls to ease the task 
of constructing professional user interfaces for Windows 3.x. 
The table custom control provides a spreadsheet-style table 
whose cells can be editable, display-only, or a combobox. 

The application can show or hide specific columns dynami¬ 
cally and the user can change the width of the column 
dynamically. The status bar custom control features a 
stretchable width field, a progress meter for showing the per¬ 
centage of completion, date or time in Windows' internation¬ 
alized format, and the keyboard state of NumLock, CapsLock, 
and ScrollLock keys. 

The toolbox custom control provides the popular toolbox 
of function buttons. You can customize the colors and group 


buttons according to their behavior. The toolbox supports 
buttons that act like toggle buttons, radio buttons, or push 
buttons. The ribbon/iconbar custom control provides a 3-D 
customizable icon bar, integrating buttons, comboboxes, and 
text in a horizontal strip. The field validation custom control 
provides input data validation by means of COBOL-like Pic¬ 
ture statements, such as PIC" “(999) 999-9999". 

The Toolskan set costs $599 and comes with complete 
MSC v6.0 source code and a 30-day money-back guarantee. 
A free demo disk is available. For more information, contact 
Kansmen Corporation, 2080-C1 Walsh Ave., Santa Clara, 
CA 95050, (408) 988-0634; FAX (408) 988-0639. 
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BOK Enhances Actor Development Tool 

BOK Technologies has released VisualObject v2.0, a tool 
that lets Actor programmers visually create tool bars and 
custom controls without writing code. VisualObject consists 
of an Actor class library and an interactive tool for creating 
windows, tool bars, and custom controls. VisualObject can 
create custom controls such as buttons (whose faces contain 
bitmaps, icons, or text), owner-draw buttons, 3-D group 
boxes, and static controls. The interactive tool automatically 
generates Windows Description Language statements and 
Actor source code. 

Custom controls created with VisualObject can have mul¬ 
tiple states and you can associate a bitmap, icon, or text 


with each state, to provide visual feedback. You can define 
the behavior for each custom control by selecting the Win¬ 
dows events it must respond to and attaching response 
methods to those events. The interactive tool can run simul¬ 
taneously with the Actor development system, so you can 
instantly test out the generated user interface from within 
Actor. 

VisualObject costs $145 and requires Actor 4.0 or later. 
For more information, contact BOK Technologies, Inc., 5476 
Trans-Island Avenue, Montreal (Quebec), Canada H3W 
3AB, (514) 485-6690 ; FAX (514) 485-2095; CIS 72730,655. 


Microsoft Introduces Professional Toolkit for Visual Basic 


Microsoft Corporation has introduced the Professional 
Toolkit for Visual Basic, a package of tools, some from third- 
party vendors, aimed at providing new functionality for 
Visual Basic programmers. New features include controls to 
handle OLE support, pen support (in the form of text boxes 
that can hold pen input), multimedia (including video, anima¬ 
tion, and CD-quality audio), graphing, grids, and MDI support 
The toolkit includes more than 15 new controls, includ¬ 
ing animated buttons, gauges, and spin buttons. The pack¬ 
age also includes the Windows help compiler, the Windows 
API online reference, a setup kit for creating standard installa 


tion programs, a coupon for a free copy of Rumba Tools for 
Visual Basic (a package for automatically creating Windows- 
based frontends to 3270 mainframe applications), and the 
Custom Control Development Kit (necessary for creating 
Visual Basic custom controls in Q. 

The Professional Toolkit for Visual Basic costs $299, or 
$495 with Microsoft Visual Basic. For more information, con¬ 
tact Microsoft Corporation, One Microsoft Way, Redmond, 
WA 98052-4399, (206) 882-8080; FAX (206) 93MSFAX; 
Telex 160520. 


MidPak Offers MIDI Sound for PC 

THE Audio Solution, Inc, has released the initial version of 
MidPak, a MIDI sound package for the PC MidPak comprises 
a set of MIDI music drivers and utilities for DOS which sup¬ 
port MIDI music output on the PC by employing Roland 
emulation for the Adlib, SoundBlaster, SoundBlaster Pro, and 
ProAudio Spectrum PC sound boards. MidPak is compatible 
with the company’s digitized sound package, DigPak v2.0. 

The included Roland Emulation Instrument File defines a set 
of waveforms that precisely model all 127 base Roland 
melodic instruments as well as all Roland percussives. 


MidPak costs $149.95 and comes with all music drivers, 
the Roland Emulation Instrument File, a set of DOS utilities, 
programmer’s documentation, example MIDI files, and 
source code examples. Licenses for commercial distribution 
of the music drivers and Roland Emulation Instrument File 
are available for single products or entire product lines. For 
more information, contact THE Audio Solution, Inc., P.O. 
Box 11688, Clayton, MO 63105, (314) 567-0267. 


Alpha Logic Introduces High-res Timer Board 


STATI (System Timing Analysis Tool) is a new board that 
provides an independent high-resolution configurable 
timebase for PC applications. The STATI board contains five 
16-bit timers that can be cascaded to provide up to 80 bits 
of timing resolution. Each timer can be configured to time up 
or down, once or repetitively, in binary or BCD. You can 
reset, load, start, stop, or latch timers in any combination 
simultaneously with a single I/O write. 

Onboard frequency generators provide base timing 
resolution ranging as low as 250 nanoseconds. STATI also 
provides a breakout switch and interface to generate non¬ 
maskable interrupts (NMls) for debugger activation. You can 
use the breakout switch to generate manual interrupts, trig¬ 
ger timing operations, or provide an input pulse to timers. 


STATI includes a low-level, general-purpose interface 
library complete with source code that allows programmers 
to quickly access timing features. This C-callable library in¬ 
cludes execution timing functions as well as low-level 
register configuration and access functions. The documenta¬ 
tion covers both the C-level API and the details of STATI’s 
register-level interface. 

STATI comes complete with add-in card, breakout 
switch, interface library, and programming guide. For a 
limited time, STATI is available for $100 off the list price of 
$395. The board comes with an unconditional 30-day, 
money-back guarantee and a limited one-year warranty. For 
more information, contact Alpha Logic Technologies, 2121 
152nd Avenue N.E., Redmond, WA 98052, (206) 644-3094; 
FAX (206) 641-6373. 
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Software Interphase Creates Live Video Toolkit 


Software Interphase has released LiveWindows, a multi- 
media video library designed to offer C and BASIC program¬ 
mers the tools necessary to write video-based applications. 
LiveWindows supports video cards based on the Chips & Tech¬ 
nologies PC Video 9001 chip and the Signetics support chips 

With LiveWindows, you can take live NTSC or PAL video 
from laserdisc, camcorder, VCR, or broadcast television, scale 
it smoothly to any size, and display it anywhere on the 
screen in a “video window,” You can open and close the 
video window with a variety of special effects, including 
wipe, curtain, explode, and fade effects. You can apply digi¬ 
tal contouring, posterizing, strobing, freezing, and color-to- 
b/w conversions to the live video. VGA text and graphics can 
overlay live or frozen video. You can even display live video 
inside non-rectangular areas, such as circles or polygons. For 
security applications, LiveWindows includes a motion detec¬ 
tion routine. 

LiveWindows supports video capturing and fast image 
processing functions. Brightness, contrast, sharpening, 


smoothing, edge detection, inversion, chrominance and 
luminance masking, histogram, and convolution are among 
the library's image processing capabilities. You can save im¬ 
ages to disk with a resolution of up to 640 by 480 and over 
two million colors, using 24-bit TIFF and Targa file formats. 
LiveWindows also supports boards that accept up to three 
video sources, three audio sources, and an onboard TV 
tuner. Applications can alter bass, treble, volume, and select 
channels. 

The LiveWindows library costs $395, or $895 including 
the motion video board (requires a VGA card with a feature 
connector). The library is written in assembly language and 
uses less than 28Kb of memory. It is available for Microsoft 
QuickBASIC, BASIC Professional Development System, 
PowerBASIC, Microsoft C, QuickC, Borland Turbo C and C++. 

For more information, contact Software Interphase, 82 
Cucumber Hill Road, Suite 140, Foster, Rl 02825, (800) 542- 
2742; FAX (401) 397-6814. 


Windows Tools and Utilities Now on CD 

Walnut Creek CDROM has released a CD-ROM containing 
80Mb of Windows software, in more than 800 software pack¬ 
ages. It includes hundreds of games, fonts, bitmaps, icons, 
drivers for a large variety of monitors and printers, and Win¬ 
dows utilities. The collection includes many programming 
tools, technical documents, and source code listings in C, C++, 
Pascal, and other languages. 

The disc contains the entire CICA MS Windows collection 
from Indiana University (a popular Internet archive for Win¬ 


dows software). The collection is indexed to make it easy to 
find files by name or subject. The disc is ISO-9660 (High Sier¬ 
ra) format, so it will work with most any system. 

The CD was created in March, 1992, and costs $24.95. For 
more information, contact Walnut Creek CDROM, 1547 
Palos Verdes Mall, Suite 260, Walnut Creek, CA 94596, 
(800) 786-9907 or (510) 947-5996; FAX (510) 947-1644. 


Style for C++ Moves to Windows 

Software Ingenuities is now shipping the Windows ver¬ 
sion of Style for C++, a class library for object management 
Style uses standard C++ constructs but allows you to declare 
the relationships between the classes in your application, 
much like a networked database. Style then handles all the 
work of maintaining links (even many-to-many) between ob¬ 
jects. You can even save, store, and load the structures you 
create with Style to disk. 

Style also allows you to define paths through the net¬ 
work of objects, in order to automate traversing the net¬ 
work for specific tasks. Part of the advantage to paths is that 


you can reorganize the relationships between objects 
without having to change all the functions that traversed the 
original structure (since paths encapsulate traversals for 
specific tasks). 

For Windows, Style also includes memory management 
functions to mask the complexity of the Windows memory 
API. Style costs $250 and runs under DOS, Windows, and 
UNIX. A future version will support OS/2 2.0. For more infor¬ 
mation, contact Software Ingenuities, Inc., P.O. Box 1586, 
Ballwin, MO 63022, (314) 391-7772; FAX (314) 391-0727. 


Win-Link Provides DOS-Windows Communications 


A well-known problem with Windows 3.x is that it is non- 
preemptive - any Windows application can hog the CPU and 
prevent other Windows applications from running. However, 
enhanced-mode Windows does preempt virtual machines, 
that is, each DOS box and the system virtual machine that all 
Windows applications run in. That means that if you could 
place your application’s user interface in a Windows applica¬ 
tion and the code that does most of the processing in a DOS 
box, your application would have most of the benefits of 
preemptive multitasking. 

The Win-Link Developer's Kit is a new software package 
that provides just this solution. By providing an interface that 
allows DOS applications and Windows applications to easily 


communicate, this package lets you place part of your ap¬ 
plication in a DOS box, where you can guarantee it will 
receive CPU time slices, even if some Windows application is 
hogging the CPU. The Win-Link Developer's Kit can also make 
it easy to add a Windows user interface to an existing DOS 
application without having to port all that DOS code to Win¬ 
dows. 

The Win-Link Developer's Kit costs $249. A free demo of 
the developer’s kit is available by downloading wldemo.zip 
from the WINSDK forum. For more information, contact Cel¬ 
tic Software, 4857 Havana Drive, Pittsburgh, PA 15239, 

(800) 223-5842 or (412) 798-9454; FAX (412) 798-0516. 
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SourceSafe Provides Multi-Project Version Control 


Icarus Software has created Icarus SourceSafe, a new ver¬ 
sion control product for DOS and Windows programmers. 

Like most version control systems, SourceSafe gives program¬ 
ming groups a central repository for checking code in and 
out, allowing only one programmer at a time to work on a 
given piece of code and providing the ability to regenerate 
any past version of the software. SourceSafe stores only the 
changes to software (where "software’ can be any kind of 
file associated with the project - source code, binaries, 
documentation, and so on) in order to reduce the disk space 
required to store all past versions. 

SourceSafe's claim to fame is its ability to handle multi¬ 
ple projects intelligently. Most version control systems have 


EMS Updates VB Library 

EMS Professional Shareware is shipping an updated and 
expanded VBASIC Library, a collection of 225 public domain 
and shareware programs, utilities, and other file collections 
specifically for users of Visual Basic With 60 new file collec¬ 
tions, the library is compressed with PKZIP to fit over 20Mb 
of material onto 20 diskettes. A Windows-based database 
directory and lookup program lets programmers locate a par¬ 
ticular type of utility or program quickly by type, vendor, 
name, or text search. 

The library contains programs and files in a wide variety 
of categories, including business, buttons, calculators, com¬ 


you establish a separate, independent directory for each 
project you wish to manage. SourceSafe, however, under¬ 
stands the concept of projects and allows you to create 
libraries of code that can be reused in multiple projects. A 
change to this core library is then correctly reflected in all 
the projects that make use of it 

SourceSafe costs $245 for a single-user license, $995 for 
five users, $ 1695 for ten users, and $3195 for twenty users. 
For more information, contact Icarus Software, P.O. Box 
11639, Raleigh, NC 27604, (800) 397-2323 or (919) 821- 
2300; FAX (919)821-5222. 


munications, custom controls, DDE, database, graphics, net¬ 
work, sound, telephone, File compression, fonts, language ex¬ 
tension, and others. 

VBASIC Library costs $59.50 and includes a list of all 
known commercial software for Visual Basic programmers. 
For more information, contact EMS Professional Shareware 
Libraries, 4505 Buckhurst Ct., Olney, MD 20832, (301) 924- 
3594; FAX (301) 963-2708. 


TeraTech Provides Math and Add-ons for VB 


TeraTech provides a variety of tools for Visual Basic 
programmers. The ProMath Library is a collection of over 150 
routines and general utilities designed as extensions to 
QuickBASIC or BASIC 7. The library is now available for Visual 
Basic and contains most of the mathematical and numeric 
functions found in Fortran. ProMath makes it easier to trans¬ 
late Fortran code to BASIC. The ProMath manual includes tips 
and pointers on translating Fortran to BASIC. 

Dazzle/VB is a library that helps Visual Basic program¬ 
mers add special effects to their applications. It provides a 
256-color control for displaying realistic bitmapped images, 
over 30 wipe screen effects, and fade and dim effects. You 
can use the library to zoom and move images dynamically 
and draw lines, circles, boxes, and fonts. The Professional Ver¬ 


Microsoft Announces MAPI SDK 

Microsoft is now shipping the first version of its SDK for 
the Messaging API (MAPI), a set of messaging function calls 
that allows developers to create message-enabled applica¬ 
tions that handle mail. The SDK contains the Windows DLLs 
that contain the MAPI calls defined in the specification. The 
MAPI specification has been published on Microsoft’s ISV 
CompuServe forum and will be available on a new MAPI forum. 


sion (which costs extra) includes RGB control, palette 
manipulation, grey scale support, and on-the-fly compression. 

VBLite is a collection of tools for Visual Basic program¬ 
mers. It includes a 256-color display custom control, a slider 
control, and a masked input box. The library supports Btree 
fast indexed searching, sorting, array manipulation, com¬ 
munications support, and printer control. 

The ProMath Library costs $125; Dazzle/VB costs $299 
(the special introductory price is $99.95), and the Professional 
Version costs $499; VBLite has an introductory price of 
$99.95. For more information, contact TeraTech, 3 Choke 
Cherry Road, Suite 360, Rockville, MD 20850, (301) 330- 
6764 or (800) 447-9120 extension 303; FAX (301) 963-0436. 


Developers interested in obtaining the MAPI specification 
can contact Microsoft Developer Services at (800) 227-4679 
(press 11771). For more information, contact Microsoft Cor¬ 
poration, One Microsoft Way, Redmond, WA 98052-6399, 
(206) 882-8080; FAX (206) 93MSFAX; Telex 160520. 


National Ships Free DAQ Designer 

DAQ Designer is a DOS program with a graphical user in¬ 
terface that helps you design a PC system for data acquisi¬ 
tion. The program asks you a number of questions about 
system requirements, such as the type and number of 
analog and digital signals, the type and number of data ac¬ 
quisition sensors, and signal conditioning needs. DAQ Desig¬ 
ner analyzes your answers and recommends specific plug-in 
data acquisition boards, signal conditioning products, cable 


assemblies, and software packages you can use to develop 
the desired data acquisition system. 

DAQ Designer requires DOS 3.x or higher, an 80286 or bet¬ 
ter, at least 640Kb of RAM, and a VGA monitor. For more in¬ 
formation or a free copy, contact Not/ono/ Instruments, 

6504 Bridge Point Parkway, Austin, TX 78730-5039, (512) 
794-0100 or (800) 433-3488; FAX (512) 794-8411; Telex 
756737 NAT INST AUS. 
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Readers' Forum 


You can now send letters to the 
editor via Internet at the following 
address: 

wdletter@rdpub.com or 
..luunetIrdpublwdletter" 
from CompuServe: 

>INTERNET:wdletter@rdpub.com 


We ask that letters with code listings 
be submitted in an ASCII text file on an 
MS-DOS formatted disk or via email. 
Providing us an electronic copy of the 
code will prevent typographical errors 
that might result from optical scanning 
or re-keyboarding. 


Dear folks: 

Your January issue contains a gold 
mine of information. I refer to the 
material on double-byte characters as 
used in Japanese computers. My wife 
(who was born and raised in Japan) and 
I are about to try our hands at translat¬ 
ing my latest US patent into Japanese - 
not a small job. (We practiced by trans¬ 
lating into English; you know, colour not 
color, etc.) 

Now, I don't have a lot of money for 
a fancy new computer and printer 
(having just shelled out over $6500 to a 
local patent attorney for a single US 
patent application and dropping a like 
amount on a trip to Japan) and so I'm 
trying to make do with my present PC 
and dot matrix printer. The articles in 
the January issue are helping with that. 

The upshot is that I've been able to 
write a batch file that creates two 
DEBUG script files for double-width char¬ 
acters, loads the resulting DEBUG output 
into printer RAM, then deletes those 
four files it created. This, using my 8088 
PC and 9-pin printer. This works, but it’s 
apparent that I must upgrade to a 24- 
pin printer for the more complex sym¬ 
bols. 

Perhaps a reader or two might be 
interested in the inelegant but effective 
file that does this. One of the simpler 


kanji is illustrated on the design matrix 
that is an integral part of the file. This 
character is one that appears on page 
29 of John Nelson's article. Notice that the 
character is made to have a full 9-pin 


height by configuring the left half as a 
descender, and the right half as an as¬ 
cender. The only parts of the file that 
need to be changed for other charac¬ 
ters (besides the file name) are the 24 


Figure 1 


Homer B. Tilton 

:KANJI001.BAT H.B.Tilton 24 Mar 1992/WK13/Tue 

:For a Citizen 180-D printer configured for IBM specs... 

Echo off 

Echo E100 IB 3D OF 00 14 "A" 01 00 00 00 CO 00 88 00 A8 00 A9 00 AF>templ.scr 


I L a 

Left-half (LH) replacement 
character 


(Use ASCII 223 for dots)—> 

A=10 

B=ll 

C=12 

D=13 

E=14 

F=15 


Right-half (RH) replacement 
character 

r a 


=00 

80“ 

40“ 

20 “ 

10 “ 

8 “ 

4“ 

2 “ 

1 “ 


I 


Echo E100 IB 3D OF 00 14 
Echo rex »temp2 . scr 
Echo 13 »temp2.scr 
Echo w >>temp2.scr 
Echo q »temp2 . scr 

Echo rex »templ.scr 
Echo 13 »templ.scr 
Echo w »templ.scr 
Echo q »templ.scr 


DEBUG %0.1 <templ.scr >nul 
DEL tempi.scr 

DEBUG %0.2 <temp2.scr >nul 

DEL temp2.scr 

COPY %0.1 PRN 

DEL %0.1 

COPY %0.2 PRN 

DEL %0.2 


I 


I 


I 


'80 
'40 
'20 
'10 
' 8 
' 4 
’ 2 
’ 1 


"B" 00 00 D4 08 54 00 54 00 44 00 60 00 00>temp2.scr 


Echo Replacement characters for %0 are: For LH "A" & for RH "B" 
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character defining bytes and the four 
places where the replacement charac¬ 
ters appear. 

Sincerely, 

Homer Tilton 
8401 Desert Steppes Dr. 
Tucson, A2 85710 


Dear Mr. Burk, 

In the April issue of WDDJ, p. 70, you 
asked for a faster implementation of 
the routine you published to convert 
ASCIIZ strings to Turbo Pascal strings. 

I think Listing 1 works fairly efficient¬ 
ly (you could do things even faster, of 
course, by resorting to assembler, but it 
was my impression that you wanted a 
Pascal solution). I'm including a routine 
that converts TP strings to ASCIIZ strings, 
too. Note that the first function has to 
make sure that the result has no more 
than 255 chars; it does so by truncating 
if necessary. 

Relative timings (obtained by ex¬ 
ecuting the functions 65000 times on a 
33MHz 80486; input is the ASCIIZ String 
This is a test sting'): 

Mr Linder's PChar2Str: 18.57 sec 

(includes loop overhead) 

The new ASCIIZ2String: 2.97 sec 

(includes loop overhead) 


Sincerely, 

Dr. Marcel Feenstra, Rl 
Managing Director, HiQ Systems 
P.O. Box 21766 
3001 AT Rotterdam 
The Netherlands 


Listing 1 


Procedure String2ASCIIZ(S: String; Var ASCIIZ: String); 

(* Converts TP string to ASCIIZ string *) 

Var 

Len: Byte; 

Begin 

ASCIIZ := S; 

Len := Length(ASCIIZ); 

Move(ASCIIZ[l],ASCIIZ[0],Len); 

ASCIIZ[Len] : = Chr(0) 

End; 

Function ASCIIZ2String(Var ASCIIZ: String): String; 

(* Converts ASCIIZ string to TP string *) 

Var 

Len: Byte; 

S : String; 

Begin 

(* Use the first 255 characters: *) 

Move(ASCIIZ,S[l],255); 

S[0] := Chr(255); 

(* Find the null-terminator: *) 

Len := Pos(Chr(0),S); 

If Len > 0 Then 

(* ASCIIZ string contained less than 255 characters: *) 
Begin 

Dec(Len); 

S[0] := Chr(Len) 

End; 

ASCIIZ2String := S 
End; 



Developer's 

Marketplace" 


Basie > C?f 


Basic is better than C when you 
use the ProBas library! Over 900 
routines, most in assembly, let you 
write fast, tight code without 
"C-headaches"! Easy to use, 30 
day money-back guarantee. For 
your FREE 20 page booklet call; 

800-447-9120 ext 110 
TeraTech 

Dept W6, 3 Choke Cherry Rd, 
Ste 360, Rockville MD 20850 
(301)330-6764 Fax: 963-0436 
BBS: 963-7478 9600-N-8-1 
"A Supercharger for Basic" - BYTE 

New Visual Basic tools available! 




Image 

Search Engines 
"plus 5000 GIFs on CD-ROM 


GlFdb by Raynbow Software allows you to 
catalog and search large collections of 
images, 

•Cataloger r\ 

•Interactive Search Engine _j (_ 
•Command Line Search Engine 
•5000 GIFs plus utilities 

on CD-ROM i pJ 

$50Sf.'... (605)394-8227 

, BBS Door Available for $50 

— 

Raynbow Software, Inc. 

P.O. Box 327, Rapid City, SD 57709 
Visa $ MC Accepted i 
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Serial Port 

Communications Tool 

SERIAL is a DOS program which turns your PC into a 
sophisticated tool for monitoring and analyzing 
asynchronous serial interface links. SERIAL captures 
both data and control line changes with time resolved to 
under 1 millisecond. Uses standard COMM hardware. 

□ Passively monitors both sides of link 

□ Easy to use window and menu controls 

□ Context sensitive help system 

□ Multiple start up configurations 

□ ASCII, Hex, EBCDIC, Custom Fonts — EGA/VGA 

□ Built-in font editor for custom fonts 

□ Multiple display window options 
O Triggers with audible alert 

□ Assisted baud rate determination 

□ Buffer string searches 

□ Support for FIFO buffers on 16550 UARTS 

□ Time stamping of both data and control lines 

□ CRC calculations 

□ Extensive technical manual 

□ Single user and corporate wide licenses 

□ Technical support 

Only $239 for single user license with 5 ft. cable, 
or $189 without cable. 

Allison Technical Services 

8343 Carvel, Houston, TX 77036 

PH # (713) 777-0401; FAX/BBS (713) 777-4746 

□ Request 114 on Reader Service Card □ 


H WindowsCreator m 

revolution !!! 

• create WINDOWS interactively 

• no need to write any code 

• You PAINT the application, not write!!! 

• object-oriented programming using 
standard C language 

• Generated C-code or Smalltalk code 
in seconds! I 

» Dialog, window, menu, cursor. 

icon, color, brush and attrib. 

editors incl. 

• interactive functionality linking 

• application code is separated from 
interface code. Few code lines connect 
application to WINDOWS interface 

AdamSoft, 66 rue de Bourgogne 
L'1272 Luxembourg 
Fax:+352-494768 VISA accepted 
Until April 30th — $ 200 , after $299 

p&p Europe $10, elsewhere $20 

□ Request 107 on Reader Service Card □ 




Visual Basic, 
BASIC, and PDS 
programmers! 

,#a#ftral Purpose Toolboxes 


^sSSraSicolions 

jrftt'ftinting 

Applications 
and more! 


Crescent Software offers many tools for 
QuickBASIC, PDS, ond Visual Basic. All 
products include complete source code, 


free technical support, and royalties are 
never required! FOS UTEMME i BH DfMO PACWCfS 

CALL TOLL FREE 

a l 800 35 BASIC 

CRESCENT SOFTWARE, INC. 

11 BAILEY AVENUE 

CRESCENT RIDGEFIELD, CT 06877-4505 
- - ~' 203 438 5300 FAX 203 431 4626 


TUB™ is FASTEST! 



RCS™ 4.2 PVCS TU TUB™ 3.0 TUB™ 5.0 


Times are to update a 45K library on a PC/XT. PVCS and TUB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer. 

TUB™ is BEST! 

“Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TUB has features and power to spare” 
John Rex, Computer Language 
“TUB is a great system” J. Vallino, PC Tech J 

. Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching, 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus'" MAKE & Slick'" MAKE. 

MS-DOS $139, OS/2 $195 + shipping visa iuc 
5 station LAN license $419 (OS/2 $595), call tor other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919) 233-8128 

□ Request 137 on Reader Service Card □ 


Disassemble MS-Windows 
Executables with ... 

• Creates detailed assembly code listings 
from MS-Windows 3jc executable files. 

• Identifies program segmentation, 
automatically! 

• Labels Window's API calls and exported 

functions, automatically! 

•Fast forward to references to specific 
Win API calls or module entry points. 

• Extracts just the function you need using 
a disassembly range. 

• Provides batch interface to define 
descriptive names and type information 
using a response file. 

• Supports 8086 - 80386. 

•Requires MS-DOS 3.xor newer. 


Man., 


,/Diik $74.95 + S/H($2US/$5lntl) 
Call or FAX (408)262-3264 
3Q-Day Monay Back Ouarantam 



Eclectic Software 

937 Jungfrau Court 
Milpitas, CA 95035 USA 


□ Request 124 on Reader Service Card □ 



Writebar Barcode Products 


Wilsoft carries a complete line of bar 
code software and hardware for your 
every need. All major bar code types 
supported. Call the most experienced 
company in the bar code field today. 
DOS and Xenix/Unix support. Por¬ 
table readers too! 

VISA/MC/AMEX/DISCOVER 

PO Box 6186 

Ft. Lauderdale, FL 33310-6186 
(305) 779-2720 
(305) 763-3096 Fax 
(800) 779-2720 Sales 


□ Request 142 on Reader Service Card □ 


Notice to Our Subscribers 

Occasionally, Windows/DOS Developer's 
Journal makes its mailing list available to 
vendors of products we think our readers 
will find interesting. Current subscribers 
receive free information in the mail from 
these vendors. If you prefer that your 
name not be used in these mailings, 
please let us know. Just copy or clip this 
form and send it with your name and ad¬ 
dress to: 

Windows/DOS 

□ DEVELOPER'S JOURNAL 

1601 W. 23rd. SL, Ste. 200 
Lawrence, KS 66046-2743 


Cica Windows CDROM $24.95 

Hundreds of Microsoft Windows programs 
on your desk! Utilities, games, fonts, 
icons, bitmaps, source code, programming 
tools, video/printer drivers, etc. 


Simtel-20 MSDOS CD $24.95 

420 Megs, 6000+ files at your fingertips! 
Programming tools, utilities, tech doc, 
comm, bbs, publishing, shells, editors, 
source code, etc. Thoroughly indexed. 


Walnut Creek CDROM 

1547 Palos Verdes Mall 


Suite 260 

Walnut Creek, CA 94596 

+1 800 786-9907 

+1 510 947-5996 
+1510 947-1644 FAX 

VisaMC 
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Opt-Tech Sort/Merge 


Extremely fast Sort / Merge / 
Select utility. Run as an MS- 
DOS command or CALL as a 
subroutine. 

Supports most languages and 
filetypes including Btrieve and 
dBase. Unlimited filesizes, mul¬ 
tiple keys and much more! 

MS-DOS, Windows $149. 
OS/2, UNIX $249. 


Opt-Tech Data Processing 

P. O. Box 678 
Zephyr Cove. NV 89448 

(702) 588-3737 
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P.S. Null-terminated strings in TPW 
have a ZERO-BASED index; therefore, _x 
in Mr Linder's program should initially 
be zero, not one, or you lose the “first" 
character (pun intended)! 

Thanks for the bug fix (how did I 
miss that?) and the all-Pascal im¬ 
plementation. I didn't even think of 
using Move(), which gives you speed 
without resorting to assembly lan¬ 
guage. —rib 


Gentlemen: 

1 received a WDDJ March 1992 with 
the magic numbers on the mailing label 
reading 110633 03.03 05.02. This, ac¬ 
cording to your description in the jour¬ 
nal, represents a two-year subscription. 


If it is really true, the only possible ex¬ 
planation I can find is that Mr. Leor Zol- 
man happened to find my tip sent to 
his column usable. In this case, thank 
you. 

Besides, I would need some help. I 
have been trying to receive IBM’s CUA 
guide for ages, in vain. Victor R. 
Volkman mentioned this guide again in 
his Fading-In-Custom Controls for Win¬ 
dows. Now I wonder whether you can 
give me a fax number to the Big Blue 
so that I can keep sending them in¬ 
quiries about the book. 

Thank you very much. 

Truly yours, 
Gabor DEAK JAHN 


One of the great mysteries of life is 
how to lay hands on certain “publish¬ 
ed" technical documents that never 
show up in any bookstore. The reason 
programmers have a copy of IBM's 
“Common User Access Advanced In¬ 
terface Design Guide” is that it used to 
ship with the Microsoft Windows SDK. 
I think that source has dried up, now 
that Microsoft is trying to publish their 
own user interface style guide (which 
you may want to get instead of IBM’s). 
I asked around for a good number at 
IBM to call, but all I got was the stand¬ 
ard “contact your nearest IBM support 
center”. I don't know where my nearest 
IBM support center is either! -rib 



Developer's 

Marketplace 


EGAD 

Screen Print Package 

• Supports VGA, EGA, CGA, 
MGA displays up to 800x600 

• Select printout colors/gray 
tones; print any rectangular 
region; enlarge graphics 1-4 
times; many other features 

• Works with most printers 

• TSR (Shift-PrtSc) or call from 
your program. TSR is 9-15K. 

• Licensing available. 

$35.00 postpaid. Free catalog. 


LS Software 8139 E. Mawson, 
Mesa, AZ 85207 (602) 380-9175 
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Y Windows Developers:^ 

Put an End to Memory Problems! 


OptiMem™ 

for Windows 


Optimal memory manage¬ 
ment DLL for Windows 3.x. 


□ Fixes selector consumption, overhead, granu¬ 
larity, fragmentation. Supports heaps > 64K. 

□ Dramatically improves performance. 

□ ANSI C malloc, C++ new, dozens more APIs. 

□ Detects memory bugs including double-freeing, 
memory overwrites, wild pointers, and more! 

□ Programmatic heap walking and error handling. 

□ Ideal for dynamic data structures, e.g. lists. 


cs 5 Only $249 + $5 s/h. Includes full source code! 
Free, unlimited technical support. No royalties. 

Unconditional 60-Day Money-Back Guarantee! 


Call now to order or to request free brochure! 

Applegate Software 


(206) 868-8512 


4317 264th Ave NE 
Redmond, WA 98053 
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INTERNATIONAL 
SOFTWARE 
ASSIGNMENTS 

YOUR PASSPORT TO AN 
INTERNATIONAL CAREER 

The International Computer Professional Association 
provides you with the world-wide contacts you need to find an 
exciting software assignment overseas. 

Every two weeks you'll receive a detailed listing of 
current software assignments faxed directly to the ICPA by 
recruiters in London, Paris, and many other cities. Youll also 
receive valuable advice from software professionals with first- 
hand international experience. 

•Learn about exciting contract and permanent position overseas 
•Make up to (70,000 tax-free, even when working In Europe 
■ Set-up an International consultancy and work throughout the world 

As a member of ICPA you become part of a dynamic 
international network of software professionals. People with 
years of experience in the international market who will show 
you how to find an assignment overseas. 

To find out more about how to join the ICPA 

Call (415) 695 7618 


□ Request 113 on Reader Service Card □ 




COM1: - COM4: 
WITH WINDOWS! 


• 1, a. OR 4 PORT RS-232 BOARDS 

• RS-23S AND RS-422 VERSIONS 

• WINDOWS UTILITY SOFTWARE 
PROVIDED 

. XT AND AT INTERRUPT JUMPERS 

• OTHER PRODUCTS INCLUDING 
LAPTOP AOO-ONS 

• DELIVERY FROM STOCK 


SEALEVEL SYSTEMS INC. 
PO BOX 830 
LIBERTY, SC 29657 

( 803 ) 843-4343 


SEALEVEL 

COMMUNICATIONS S I/O 
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CREATE MULTI¬ 
LINGUAL PROGRAMS 

Translator^ Apprentice Toolkit 

Access the huge international market by 
converting your C programs to externalized text 
for easy translation into other languages (Spanish, 
German, etc.]. The Translator's Apprantica is a 
complete extemalization and text management 
package. 

□ Automatically converts existing source code. 

□ Different language versions without source 
changes. 

□ Create a single executable containing external 
text. 

□ Unlimited text size; Fast! access. 

□ Reduced memory requirements. 

□ Export/Import ASCII text. 

□ Multiple simultaneous languages. 

□ Translation service available. 

3Cday money-back guarantee. Order now, $175 
including program, access functions, source. 

C or Clipper. 

Frontier Software Services 
31 Mystic Ave. 

Winchester, MA 01890 
[SI 7) 759-5161 _ 
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July 1992 























WINDOWSTOOLS 
FILE MANAGEMENT 

This professional Windows utility package includes 
Multicopy, Systemlnfo, TextSearch, and TextEdit. 

Multicopy is a fast copying utility that supports the 
Windows Memory Manager and can use RAM disk and 
hard disk during the copying process. Formatting, multi¬ 
ple copying, and successive numbering are also included. 

Systemlnfo shows in a single glance how your 
computer's resources are used in the Windows environ¬ 
ment A graphic diagram depicts the amount of space 
occupied by your programs, data, and directories. 

TextSearch is a fast and fully functional text search 
program. TextSearch locates specific positions within 
files, directories, on hard disks, even on your network. 

TextEdit allows you to view and edit your files in 
hexadecimal or character oriented styles. TextEdit also 
includes the ability to edit several fdes simultaneously 
(MDI). Files can be up to 64 MB. All for $98! MC/V 

The OXKO Corporation 

P.O. Box 6674, Annapolis, MB 21401 

Tel: (301) 266-1671 Fax: (410) 266^572 
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Windows Edit Controls 

InControl Toolbox. Custom Windows 
edit controls for the entry of: 

□ Integers, Floating point 

□ Dates 

□ Formatted Text 

□ Regular Expression 

□ Display of date and time 

Provides hooks for programmer 
validation routines and creation of 
specialized controls. 

For demo, call BBS: (512) 335-5079 
Without source $99. With source $249. 
For info or orders call: The Connection 
800-336-1166 or (216) 494-3781 
Fax: (216)494-5260 


MantaSoft Partners (512) 335-3497 

P.O. Box 203551 
Austin, TX 78720-3551 
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OORTK 


The Object Oriented Multi-Tasking 
Real Time Kernel for Turbo Pascal 


Features: 

✓ Tasks and Communication 
Primitives defined as objects 

✓ Dynamic Task management with: 

• Number of tasks only limited by 
hardware 

• Local stack frame for each task 

• Recursive task definition 
possible 

✓ Variable Time-Slice 

✓ Multi-level Priority Dynamic Task 
Scheduler 

✓ Inter-Task communication using: 

• Binary and Multi-Level 
Semaphores 

• Mailboxes 

• Ada Style Rendezvous 

✓ Resource Sharing 

✓ Kernel requires less than 6K of 
memory 

✓ Allows both local and shared data 


In Use: 

✓ Fully compatible with Turbo Pascal 

✓ Straightforward operation 

✓ Comprehensive manual 

✓ Sample programs 

✓ Royalty-free application generation 
(.EXE form) 

Requires: 

✓ IBM PC-XT, AT. or compatible. PS/2 or 
386. 486 

✓ 512K RAM (for Turbo Pascal 
development) 

✓ DOS 3.xx or higher 

✓ Turbo Pascal V5.5 or V6 

Price: 

Full system license Si95.00 » $5.00 
shipping 

Demonstration disk $5.00 (refundable with 
order) 


To Order send check or money order to: 


The Pixel Shoppe 
5 Blackberry Lane 
Whitehouse Station, NJ 08889 
Phone 908-534-2463 
NJ Residents add 7% sales lax 

eMClusivcty tn th« U.S. by Th. Pti.t Show und.r from JPS Gr»p*oc» brrd MrcropnxcMor Syyum, Dcugn 

Turbo Pascal it a trademark of Borland Inlemalional 
IBM i, a trademark of kuemalional Buvnest Machine, 


SDLC, HDLC 
And X.25 Support 

Use Sangoma hardware and software 
to provide fast, cost effective, robust 
and easy to use SDLC, HDLC and X.25 
links from MS-DOS, UNIX, Concurrent 
DOS etc. 

All real time communication functions 
are performed by intelligent coproces¬ 
sor card. Line speeds up to 160 kbps 
are supported. Powerful debugging, 
line statistics and trace facilities are 
included. 

Full function SNA emulation packages 
also available. 

Sangoma Technologies Inc. 

w (416) 474-1990 (800) 388-2475 


2 tm 

The Art of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective. Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 


ETN Corporation 

RD4 Box 659 Montoursville, PA 17754-9433 
(717) 435-2202 (Sales) (717) 435-2802 (FAX) 
AMEX/MC/VISA/Check/MO/PO/COD 
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C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, functions-vs-files index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59) Counts path complexity, 
counts comments, code, 'C' statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• C-DOC SPECIAL ($1991 All 5 programs 
integrated as 1 DOS program. Processes 
multiple directories/files up to 15,000 lines. 

• NEW! ($2991 C-DOC Professional 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deferred reports. 
ObT3A1^one^4oacl^uarante^CA^^OW 

SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga 

ONT, Canada. L5N-4M1 (4161-858-4466 


see AD INDEX for our larger ad 
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Z-PHIGS" 

Use the power of most advanced graphics 
development system available today. 


Z-PHIGS is an enhanced implementation of the only 
recognized 3D-graphics standard PHIGS + for DOS 
and Windows. It provides everything needed to de¬ 
velop high-performance graphics applications. A 
powerful library with 2D/3D functions and a highly 
optimized data management system save you years of 
development time in the fields of CAD/CAM, Simu¬ 
lation, Multimedia, etc. Most sophisticated rendering 
capabilities like Lighting, Shading, Reflections, Tex¬ 
ture-Mapping, etc. makes it simple and quick to give 
your Windows products those spectacular 30-graph¬ 
ics features that will put your compititions to shame. 
Language bindings are available for Pascal or C. 

For DOS $795, for Windows $1590 
VISA and MasterCard accepted. 


WISE Software, Seelandstr.3, 2400 Liibeck 14, Germany 
Tel: (+49)451-3909-413 Fax: (+49)451-3909-499 
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32-bit Protected Mode 
386 C Graphics Library 

Intel 386/486 C Code Builder 
MetaWare, MicroWay, SVS, 
Watcom & Zortech with 
Phar Lap 3861 ASM 

Mixed Raster/Vector, 
Scalable, Rotatable Font, 
VGA, SVGA, 8514/A, VESA, 
Hercules Graphics Station 
through 1024x768x256 (8-bit), 
640x480x32k (16-bit), 
512x480x16.7m (32-bit), 
WYSIWYG HP-GL/PostScript 
$200 NO ROYALTIES 
FULL SOURCE CODE 
Gary R. Olhoeft 
P.O. Box 10870 Edgemont 
Golden, CO 80401-0620 
303-877-3697 CIS 76665,2021 
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NETWORK 

CONTROL 

LIBRARIES 

NETBIOS ROUTINES allows ac¬ 
cess to low-level network func¬ 
tions. Name, session, and 
datagram routines. Wait and no¬ 
wait options. $99 

NETBIOS DLL for Windows $199 

NETWORK MASTER provides 
access to Netware internal func¬ 
tions. Complete network control 
from your compiled programs! $99 

Starlight Software 

P.O. Box 1090 

Wheeling, IL 60090 

(708) 394-0622 _ 

□ Request 170 on Reader Service Card □ 
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windows/DOS Code Listings 
Available via UUCP! 

The listings for all code in each issue of Win¬ 
dows/DOS Developer’s Journal are now being archived 
in machine-readable form by UUNET Technologies, Inc. 
Each archive file has a pathname of the form 

uunet!~/published/windowsdos/19YY/monYY.tar.Z 

where mon is the first three letters of the month (jan, 
feb, etc.) and YY is the last two digits of the year (e.g., 
92). To uncompress the archive file, use compress -d 
files-, then use tar xvf file to expand the archive 
into its component files. See the file called 
filename.txt, included in each archive, for an explana¬ 
tion of the archive's contents. 

You may download these archive files via uucp 
even if you do not have a UUNET account: have your 
uucp program call 1-900-GOT-SRCS and use the login 
name uucp, no password. Callers will be charged a 
nominal fee for connect time (currently 50 cents per 
minute). The modems are mostly Telebit T3000's, 
which support most of the faster communication 
protocols. 

Code for each issue is also available on diskette from 
R&D Publications at $5.00 per disk (call 913-841-1631 for 
information). 


ST@>P! 


Over 18,000 
Windows developers 
are reading this ad. 
Shouldn’t your product 
be here? 

Call us at 913-841-1631 
to receive a free media kit. 
You’ll be glad you did. 

Windows/DOS 

□ DEVELOPER'S JOURNAL 


CALL 

913 - 841-1631 

TODAY! 


Page 72 — Windows/DOS Developer’s Journal 


July 1992 





















































































FREE 

Product 

nformation 

Use this postage paid 
card to stay up-to-date 
on products 
that affect 
your productivity. 

Just fill out the card 
and drop it in the mail. 
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Windows/DOS 

□ DEVELOPER'S JOURNAL 


1601 W. 23rd St., Suite 200 
Lawrence, KS 66046-9950 
(913) 841-1631 FAX: (913) 841-2624 


Please help us serve you by 
answering the following: 

1) I program: 

□ for a living 

□ as a hobby 

□ as a manager 

2) I program in: 

□ MS-DOS 

□ Windows 

3) I program most frequently in: 

□ C+ + 

□ Assembly 

□ Pascal 

□ BASIC 

□ C 

□ Other _ 

□ Please send me subscription information. 


REQUEST READER SERVICE NUMBERS: 



WindowsyPOS 

□ DEVELOPER S JOURNAL 

□ YES! Send me 12 issues of Windows/DOS Devebper’s Journal for only $29! 

□ 2 years (24 issues) for $54 □ 3 years (36 issues) for $77 

□ Bill Me tZI Visa □ MasterCard 

Number_Exp._ 

Signature_ 


Name 


Company 


Address 

City 

State 


Zip 


Country/Province/Mailcode 


3.7 


Please allow up to six weeks for delivery of first issue. Orders outside the US must be prepaid in US funds. CANADA/MEXICO 
subscriptions are: 1 year - $53; 2 years - $88; 3 years - $121. Overseas subscriptions are: 1 year - $64; 2 years - $120; 3 years - $174. 
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The All New Third Annual Summer 


WINDOWS & OS/2 CONFERENCE 


August 19-21, 1992 • Tutorials: August 18 • World Trade Center, Boston 


65 + 

TUTORIALS, 
CONFERENCE 
SESSIONS, 8t 
FAST TRACKS 


“An absolute must for all 
Windows users! It’s hot!” 

Tony Odom 
Systems Management Group 

“An innovative approach to 
solving everyday Windows and 
Windows application problems 
coupled with an excellent A/V 
presentation and a well- 
versed, informative presentor. ” 

Alan Gibbins 
Boeing Canada 





KEYNOTE 

Alan Kay 

Visionary, Apple Fellow 
Father of the Personal 
Computer 

“Turning Visions 
Into Reality” 

Plenary Session 

“GUIs... And Then What?” 
Ed Bott, Editor-in-Chief, 
PC/Computing 

Developer's Keynote 

“Success Is An Object " 
Eugene Wang, Vice President, 
Borland International 

Strategy Briefings 

IBM: Fernand Sarrat 
Microsoft: Dwayne Walker 
Lotus: John Landry 


THE EXPOSITION 

200 Top Exhibitors 


The Network 

Computing 

Showcase 

Sponsored by LAN Times 

ShowDisc™ CD-ROM 

Pick up your free multimedia disc 
at the show—featuring 
product demos, 
Windows & 
OS/2 editorial, 
plus the com¬ 
plete Windows & 
OS/2 Conference 
Program Guide on CD-ROM. 
Produced by SelectWare 


The Multimedia 
Showcase 

Sponsored by Windows 
Magazine. 

The Multimedia 
Test Drive Center 



Applications & 
Development Tools 
Presentation Stages 

Sponsored by InfoWorld. 

Technical Seminars 

Sponsored by the Boston Computer 
Society. 

FREE Test Drive 
Centers, Hands-On 
Workshops, 
Presentations 
Galore! 

VIP Gold Bonus Book 

Packed with coupons worth $thou- 
sands in FREE demo disks, product 
give¬ 
aways, 
special 
show 
dis¬ 
counts 
and much 
more! Sponsored by PC World. 



Windows&OS/2 


E N C E 


For Immediate information on our upcoming Windows & OS/2 Conferences 

Call us at 1 -800-466-2684 

FAX 1-510-601-5075 or MAIL this coupon 


Free Hi Valuable Information on Implementing Windows & OS/2 

— Just for the Asking. Receive the valuable reports and industry newsletters listed in the 
coupon below simply by requesting information on our next Windows & OS/2 Conference. 


I’m Interested! 

Please rush me information on: 

□ Conference Program 

□ August 18-21,1992, Boston 

Name 

□ Exhibiting 

□ January 19-22, 1993, San Jose 

Tide 

Company 

Address 

City 

State Zip 

Phone ( ) 

Fax ( ) 


Please rush me these FREE reports: 

□Windows 3 0/3.1 Character Sets DOS/2 2.0 Experts Advice □ Windows 3.1 Tips & Tricks 
And send me a sample copy of the following newsletters: 


□ Carole Patton’s ACKnowledge, 

The Window Letter 

□ Andrew Seybold’s Outlook 

□ Multimedia Computing & Presentations 

□ Tom Hargadon’s The Green Sheet 


□ CompuServe Multimedia Forum sign¬ 

up kit (New members only; $ 15 value) 

□ Jeffery Tartar's Soft*Letter 

□ Amy Wohl’s TrendsLetter 

□ Jesse Berst’s Windows Watcher 


Please indicate others at your location who should be added to our mailing list 
(add additional sheets if necessary): 

Name 

Title 


Name 

Title 


Name 

Title 


Windows & OS/2 Conference Is Produced & Managed by: 
CM Ventures, Inc., 5720 Hollis Street, Emeryville, CA 94608 
Phone:510-601-5000 • Fax: 510-601-5075 
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Get Inside WINDOWS! 






Microsoft 

WINDOWS 

r Vruon Compatible Prodixi 


Debug Windows at the systems level! 


Soft-ICE/W takes you inside Windows! Debug and explore with power 
and flexibility not found in any other Windows debugger! Soft-ICE/W 
allows you to debug at the systems or applications level or simply learn 
the inner workings of Windows. 

• Debug VxD's, drivers and interrupt routines at source level 

• Debug interactions between DOS T&SR's and Windows Apps 

• Debug programs in DOS boxes 

• Display valuable system information 

(from the total memory occupied by a Windows application, to the 
complex internal structures of Windows) 

Soft-ICE/W uses the 386/486 architecture to provide break point 
capabilities that normally require external hardware. Nu-Mega, which 
pioneered this technology with the introduction of its award winning 
Soft/ICE for DOS, now gives Windows programmers the same debug¬ 
ging power... and still at a software price. 

Own the debugger that combines the best "view" of Windows internals 
with the most powerful break points of any software debugger. 

Soft-ICE/W. . . Only $ 386 

CodeView for Windows users: see what you're debugging without flash. 
CV/1 version 2.0 runs CodeView in a graphics window while viewing your 
application screen. Runs on anv display that supports Windows. 

CV/l . . . Only $129 

Buy any Nu-Mega product and get CV/1 for only $69. 


— WHAT THE EXPERTS ARE SAYING - 

"Soft-ICE for Windows is great! It helped me 
find, in fifteen minutes, a killer bug in a 
Windows virtual device driver that had 
eluded two people for several months. I 
can't see doing Windows development of 
any kind -- whether writing Windows 
applications, device drivers, or even DOS 
programs that have to run under Windows - 
without it. In addition to being great for 
finding bugs, Soft-ICE for Windows has been 
essential for my work on a forthcoming book: 
on Undocumented Windows . Soft-ICE for 
Windows goes anywhere and does 
everything, so it's essential for anyone who 
wants to poke around inside Windows 
Enhanced mode. DOS programmers will find 
it a perfect way to learn how the Windows 
DOS extender and DPMI server work, and 
how Windows interacts with DOS. Windows 
Enhanced mode is the hacker's paradise of 
the 90s, ond Soft-ICE for Windows is the tool 
that every serious Windows or DOS hacker 
will need. Nu-Mega has done a brilliant 
job!" 

Andrew Schulman 

Software Engineer. Phar Lap Software 

Editor, vnd vcu mn tecl DOS 

Coauthor. Undocumented Windows (forthcoming) 


Call (603) 889-2386 
fax (603) 889-1135 
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RISK = NULL 

30 DAY 

MONEY-BACK GUARANTEE 

P.O. Box 7780 

Nashua, NH 03060-7780 U.S.A. 

'technoloc 

jIES INC 



MICROSOFT WINDOWS IS A REGISTERED TRADEMARK OF MICROSOFT CORP Soll-ICEAV AND CV/1 ARE TRADEMARKS OF NU-MEGA TECHNOLOGIES, INC. 
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